logoBack to home screen

Installing ADx - Overview

If you don't want to use Docker or Kubernetes, you can install ADx using a provided .zip archive which contains all required tools and resources necessary for a local installation. This document will guide you through it. Read about the Prerequisites first, then proceed to Installation. You can also find important information regarding the package contents here.

Prerequisites

  • Linux server environment with a user having the write access.
  • tesseract and wkhtmltopdf - these tools are used by the conversion cartridge to extract text from images (tesseract) and convert HTML files to PDF (wkhtmltopdf).
  • In order to avoid low server entropy, we recommend to install Haveged before proceeding.
  • Curl must be installed - it's required by the health check script. This package has been tested with versions 7.58.0 and newer.
  • Java version 8 (recommended). Java up to version 10 is allowed, however there are some known issues you need to be aware of. This package has been tested with Openjdk, but Oracle JDK and other compatible JVMs are known to work as well.
  • Environment variable JAVA_HOME must be set and [JAVA_HOME]/bin must be on the PATH. Alternatively, one can provide an environment script to set these variables, see below.
  • A running database - you will need the URL (host name and port) and user credentials. Database setup must be provided by your organization.
  • A valid license file. If you don't have a license yet, please request it from your contact person at Braintribe.
  • Deployment package files are downloaded (Conversion and ADx Core).

Cluster Prerequisites

  • Load balancer servers must be set up for Conversion and ADx Core if you want to run ADx in a clustered environment. Similarly to the database, load balancer must be provided by your organization.
  • A shared file system for ADx and Conversion clusters must be provided, so that all nodes have access to same files (such as uploaded documents or conversion files).

Installation

Local ADx installation consists of the following stages, which you need to carry out in the presented order (follow the link for each step):

  1. Installing the conversion service
  2. Installing ADx Core

Versions

The version of the installed package is displayed in the following places:

  • The landing page (at the bottom)
  • The README file in the package
  • In the terminal output when running install.sh

You might see that a package you downloaded (or want to download) has a suffix after the revision in its name, as in:

2.0.61-p2

This is related to internal processes and only indicates a very minor change in the package (like a small update to the README). You only need to know the package version (i.e. the -p suffix number) for troubleshooting, if your installation fails.

What is important when downloading packages is to know that when you download from the major.minor folder (such as 2.0), you will always get the latest version of the software. Consider the situation below:

In this case, the .zip file contents under 2.0 are the same as in 2.0.64-p2, which is the latest package produced. The links below would have the same content:

https://artifactory.braintribe.com/artifactory/webapp/#/artifacts/browse/tree/General/releases/adx/deployment-package/2.0.145-p2/adx-deployment-package-2.0.61-p2.zip

https://artifactory.braintribe.com/artifactory/webapp/#/artifacts/browse/tree/General/releases/adx/deployment-package/2.0.145-p2/adx-deployment-package-2.0.zip

Advantage of the long version links is that one immediately sees the full version in the file name. Advantage of the short version link is that the link itself is stable, i.e. doesn't have to be updated for every update.

Deployment Package Contents

Your package should have the following contents:

File / FolderDescription
resourcesFolder containing tools and resources required for local deployment. Do not modify this folder!
check-health.shScript that runs a health check against the specified URL. This can be used as an after-setup test to verify that deployed services are available and work properly.
encrypt.shScript that encrypts the passed value. This is used to avoid clear text passwords in configuration files. See Password Encryption for more information.
example-environment.shIf this is the first deployment, you may want to create an environment script which sets the environment variables. This is useful in environments where multiple Java installations are available and JAVA_HOME doesn't point to the one that's supposed to be used for the installation. The easiest way to create the environment script is to copy this file to the default location (explained in installation instructions). Afterwards, simply open the file in a text editor and set respective values.
example-installation-settings.yamlExample configuration file which you can use as a template.
install.shScript that performs a local installation, i.e. Tomcat setup and asset deployment. Run install.sh to display usage information.
jinni.shScript that runs Jinni with the specified request. Jinni is the Tribefire setup tool. It is used for various setup related tasks such as asset downloading, Tomcat setup, Docker image building, Kubernetes manifest creation or password encryption. It therefore supports a lot of different commands for different use cases. For further information about Jinni run jinni.sh to display usage information or jinni.sh help to list the available commands.
This deployment package has been built specifically for local installation. It's usually not required to run jinni.sh directly. Instead one can just use the provided convenience scripts (see above). These scripts also use Jinni, but require less parameters, and are thus easier to use.
READMEReadme file with basic information, linking to the documentation.

Miscellaneous

Environment Variable Script

If you decided to run a script to set your environment variables, the easiest way to create the environment script is to copy the file example-environment.sh included in this package to a location of your choice. Afterwards, simply open the file in a text editor and set respective values:

#!/bin/bash

# This is an example environment script which can be used as a template to easily create your own file.

# exit when any command fails
set -e

# set Java installation path
export JAVA_HOME=/path/to/jdk
# add Java's bin folder to the PATH variable 
export PATH=${JAVA_HOME}/bin:${PATH}

When you have set the values, save your new script. It's now ready to be referenced by the encryption, installation, and health check scripts by adding the --environment /path/to/environment.sh part to the command as in:

Installation reference:

./install.sh --settings /path/to/installation-settings.yaml --environment /path/to/environment.sh

Encryption reference:

./encrypt.sh --value 'my-password' --environment /path/to/environment.sh

Health check reference:

./check-health.sh --url https://localhost:8443 --environment /path/to/environment.sh

Password Encryption

All passwords in your configuration files must be encrypted. You can use the encrypt.sh script which is provided in your deployment package for that purpose. Note that an unencrypted password will not work, resulting in tribefire-services crash after installation.

To encrypt a password:

  1. In the command line, run the ./encrypt.sh --value 'example-password' command, for example ./encrypt.sh --value 's3cur3p455w0rd'. The encrypted password is then displayed:

    $ ./encrypt.sh --value 's3cur3p455w0rd'
    cNRVe5T5gOB0o3NXxjCdRkiMGbNKWpAsbGFWFVKCVjZ0Jh1yUwyaZxPJ1WjFYbXABc6qiw==
    
    DONE
    

    Note that you can reference the environment variable script while encrypting your password by adding --environment /path/to/environment.sh to the command.

Copy the encrypted password to the clipboard and paste it to the configuration file, then wrap it in "${decrypt(' encrypted_password ')}", as in "${decrypt('cNRVe5T5gOB0o3NXxjCdRkiMGbNKWpAsbGFWFVKCVjZ0Jh1yUwyaZxPJ1WjFYbXABc6qiw==')}".

Starting the Tomcat Server

Once the installation has finished, it is time to start the application. You can either start the server from command line, or as a Linux service.

Starting the Server from the Command Line

  1. Navigate to the target installation directory, go to /runtime/host/bin, and run the catalina.sh run command.

Executing this script starts Tomcat and deploys the web applications. Tomcat prints a log message when the server startup completed:

Server startup in [53,178] milliseconds

Starting the Server as a Linux Service

After installation, you can find a Linux script file in the runtime/host/bin/ folder: tribefire-service.sh. It can be used to install the Tomcat server as a linux service. At the moment we support the following Init systems: sysvinit and Upstart.

  1. Run sudo ./tribefire-service.sh install as a root user. Provide the password when prompted.

    This will create a symbolic link to this script in /etc/init.d and register it as a service:

    sudo ./tribefire-service.sh install
    Assigning execution rights to start/stop script
    Creating a reference to the start/stop script in /etc/init.d
    Registering conversion as a service
    Registering conversion using /usr/sbin/update-rc.d
    Done with registering service conversion
    

    To uninstall the service, simply run sudo ./tribefire-service.sh uninstall.

  2. Once it is installed, the service can be used to start and stop the server:

    • To start, run /etc/init.d/service_name start
    • To stop, run /etc/init.d/service_name stop

    Where service_name has to be replaced with the name provided in projectDescriptor property inside the configuration file (defaults are conversion for the conversion package and agile-documents-platform for the ADx package).

Note that there are other ways to start Tomcat, e.g. also as a background service. For more information refer to Tomcat documentation.

Testing the Deployment

You can perform a number of health checks on your deployment to make sure everything is running smoothly. For details, see Running Conversion and Platform Health Checks.

Logging

After installing Tribefire, you can access all logs in your installation directory, under /runtime/host/logs. Note that you can change the log location. To do so, add the path to the logFilesDir: property in the logging section of the configuration file, as in logFilesDir: "/path/to/external-storage/logs".