This guide describes how to install Axional Docs

1 Requeriments

To startup a server a minimum software should be installed in the guest Linux computer

  1. A Linux operating system with at least 2 GB of RAM.
  2. The last release of Java 11.
  3. The internet connection must be enabled, due the install files are downloaded from an external repository.

Axional Services is needed for performing expensive transformations. It is used by Axional Docs servers to delegate the following document transformations:

  • fo to pdf
  • dot to svg
  • ditaa to png

See Axional Services Installation Guide here.

1.1 Java

A Java 11 SE machine is required to run the application.

Run the following command in a terminal to check the current Java version:

Copy
$ java -version

If Java is already installed, you can see a similar result like:

Copy
$ java -version
openjdk version "11.0.1" 2018-10-16
OpenJDK Runtime Environment 18.9 (build 11.0.1+13)
OpenJDK 64-Bit Server VM 18.9 (build 11.0.1+13, mixed mode)

If not satisfied then it can be downloaded here.

Axional Docs check differents JAVA locations, one of them is /opt/jdk1-11* so you can do a symbolic link from this path where the JDK was installed.

Copy
ln -s TARGET /opt/jdk1-11.0.1

Check this article for help on Java 9 setup.

After the Java Installation you should define the JAVA_HOME environment variable pointing to your Java Install Directory. Alternatively you can define a full server access to installed Java by setting up the linux alternates:

Copy
# update-alternatives --install "/usr/bin/java" "java" "/opt/jdk-11.0.1/bin/java" 1
# update-alternatives --install "/usr/bin/javac" "javac" "/opt/jdk-11.0.1/bin/javac" 1
# update-alternatives --install "/usr/bin/javaws" "javaws" "/opt/jdk-11.0.1/bin/javaws" 1

# update-alternatives --set java   /opt/jdk-11.0.1/bin/java
# update-alternatives --set javac  /opt/jdk-11.0.1/bin/javac
# update-alternatives --set javaws /opt/jdk-11.0.1/bin/javaws

If you want to change alternates manually, you can use config parameter to select your prefered JVM version

Copy
# update-alternatives --config java
# update-alternatives --config javac
# update-alternatives --config javaws

1.2 Create an user 'docs'

We recommend to install it, in the /home/docs/axional-docs directory.

As root user, proceed to create the user docs:

Copy
$ su - root
$ useradd docs
$ passwd docs

After the user docs is created, do login with this user and create the folder where the software will be installed:

Copy
$ su - docs
$ mkdir axional-docs
$ cd axional-docs

1.3 Axional installer

Working as docs user, on directory /home/docs/axional-docs download the installation tool using the common curl and tar commands:

Copy
$ su - docs
Copy
$ curl -k -s "https://bitbucket.org/deister/axional-install/get/until-2018.tar.gz" | tar -x -z --strip-components=1 --exclude ".hg*" --exclude

2 Install the application

Firstly, use axional installer to setup remote software repository and credentials.

You need to ask your Deister representative for a nexus username and password to access deister nexus software repository

Use the shell to install the product

Copy
$ ./install.sh install
* Looking for curl...
* Looking for unzip...
* Check Java ...
  = Found java executable in PATH
  = Java version 11.0.1
* Looking for gradle
* Trying to download Gradle distribution (https://services.gradle.org/distributions/gradle-4.10.2-bin.zip)

First time you execute the installer, it will ask for some parameters to configure installation. You'll be asked for a user and password for accesing deister nexus repository. Ask for it to deister support team.

2.1 Connection details

The installer will prompt for connection parameters to the Nexus repository such as the url, user and password

================================================================
CONFIGURATION
================================================================

Nexus Base URL [http://nexus.deistercloud.com/]:
Nexus User []: UserProvided
Nexus User Password []: PassProvided
                

2.2 Choose product

Next the the installer will prompt for product. We will enter docs.

The script will prompt for weather we want to download DB exports (dictionaries) along with the docs product, or not.

Do you want to download DB exports for standard dictionaries? [y/n]

2.3 Choose the version

We will choose to install a development version. Development versions are released more frequently and include the latest changes in code.

Production Environment

For Production Environment install a release version. Check guide here

2.3.1 Installing a development version

To install a development version, answer y to the question:

Do you want to download from the SNAPSHOT repository? y

Before continuing the installer will review the parameters:

CONFIGURATION PARAMETERS
--------------------------------------
NEXUS_BASE_URL: http://nexus.deistercloud.com/
NEXUSUSER.....: UserProvided
NEXUSPASS.....: ************
NEXUSPRODUCT..: docs
PRODUCTNAME...: axional.docs
PRODUCTVERS...: 0.0.+

Are You Sure? [y/n]

This questions are asked only first time and stored in file .install.rc. Following use of install.sh shell, will use parameters answered for accesing deister nexus repositories.

3 Configuration

The server configuration is stored in the XML file config.xml (located in the "conf" folder in the application path).

3.1 External information

The Axional Docs application implements a mechanism to retrieve information from an Axional Docs server. The parametrization to allow getting that information is done on the configuration file, node application/services. For example, it can be as follows:

<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="cmsConfig">
    ...
    <backendUrl>http://localhost:8080/soap/servlet/rpcrouter</backendUrl>
    <backendUsername>docs_user_code</backendUsername>
    <backendPassword>docs_user_password</backendPassword>
    <backendDatabase>acme_db</backendDatabase>
    ...
</application>

4 Service management

Axional Docs provides the shells to start and stop the application and more shells utilities to help obtain system information. Use the provided shell script start.sh to start and stop.sh to stop the application.

4.1 Start the service

To start the service use the option:

Copy
$ bin/start.sh

to start the service setting the JVM parameters for memory.

4.2 Stop the service

To stop the service run use the option:

Copy
$ bin/stop.sh