logoBack to home screen

Installing ADx Core

Having installed and started the conversion service, you can follow this procedure to install ADx Core. When you finish this procedure, you can start using ADx.

The installation process is almost the same as for the conversion service. The difference is that now you won't have to enter conversion database data in the configuration file, because you have already set it up with the conversion service. Instead, you will simply link to the conversion service from runtime properties.

Prerequisites

Installation

Follow this tutorial to install ADx from a package. Make sure to meet the prerequisites first.

  1. Unzip your package to a directory of your choice.

    When done, your package is unzipped to this directory, to a sub-folder (adx-deployment-package or similar). When you open this folder, you should see the following files:

  2. Open the terminal from the adx-deployment-package folder presented above and run the following commands:

    On Linux:

    mkdir ../additional-libraries
    
    mkdir ../license
    
    # Copy only if you want to set environment variables with this script. Remember to edit the file and adjust the values.
    cp example-environment.sh ../environment.sh
    
    cp example-installation-settings.yaml ../installation-settings.yaml
    

    On Windows:

    mkdir ..\additional-libraries
    
    mkdir ..\license
    
    # Copy only if you want to set environment variables with this script. Remember to edit the file and adjust the values.
    copy example-environment.bat ..\environment.bat
    
    copy example-installation-settings.yaml ..\installation-settings.yaml
    

    As a result, you have now created the license and additional-libraries folders next to the adx-deployment-package folder, and copied the template files with the installation settings and the environment script:

    Note that you will only ever need the environment script if Java directory is not yet added to the PATH on your machine. If that's the case, click here for more information.

  3. Put the license file provided to you in the license folder. If the file is provided as a .zip archive (or similar), unzip it into this folder. Example: license/example-license.sigxml.glf.

  4. Add the database driver to the additional-libraries folder, as explained below.

    1. First, you need to download the correct driver. Knowing the database type used by ADx in your organization, download one of the below drivers:

      DatabaseDriver download page
      PostgreSQLDownload. Important: PostgreSQL has been tested with driver version 42.2.6. Please use this version or newer.
      OracleDownload
      MSSQLDownload. Important: MSSQL has been tested with driver version 7.2.2 and is reported to work with versions 6.3.2 and newer. Do not use older drivers.
      DB2Download
    2. Now, add your driver to the additional-libraries folder, available in the package:

      When downloaded, simply copy and paste the driver file into this folder.

Mandatory Configuration

Open the installation-settings.yaml file in a text editor of your choice and edit the sections mentioned below (and only these sections).

Installation Path

When installing, you will need write access to create the below-mentioned path.

You can either use the default path or set the installationPath: property to the installation directory of your choice. If you do, remember to provide an absolute path in the configuration file. As a result, conversion service will be installed in the provided directory. All relative paths used in the configuration file are resolved from the installation directory.

The result should present itself as below:

# ** Installation Path **
# The directory where the application will be installed. Note that files from previous installations may be overridden.
# Note that there are other (relative) paths specified in this file, which will be resolved relative to this installation path.
# For example, if path is '/opt/braintribe/adx/tribefire', the (default) log files directory is '/opt/braintribe/adx/logs'.
installationPath: '/opt/braintribe/adx/tribefire'

Ports

The ports determine the URL under which ADx will be available when installed (as explained by the comments). For example http://hostname:8080 or https://hostname:8443.

Initially, this section looks as follows:

# ** Ports **
# The following settings are used to configure ports where server listens for requests.
# If multiple nodes are installed on the same machine, ports have to be adapted for node.
# It usually makes sense to just change the first digit to use another port range.
# Example: node A uses 8xxx (i.e. 8080,8443,8009,8005), node B uses 9xxx (9080,9443,9009,9005), node C uses 10xxx (10080,10443,10009,10005).

# The HTTP port where the server listens for requests. If set to e.g. 8080, HTTP (base) url will be http://[host]:8080/.
httpPort: 8080
# The HTTPS port where the server listens for requests. If set to e.g. 8443, HTTPS (base) url will be https://[host]:8433/.
httpsPort: 8443
# The AJP connector port (see https://tomcat.apache.org/tomcat-9.0-doc/config/ajp.html)
ajpPort: 8009
# The Tomcat server port (e.g. for shutdown commands)
serverPort: 8005

Important! If you are installing ADx Core and Conversion on the same machine, make sure you give each of them unique port numbers. Also, make sure the AMQ_SERVER_PORT port is different for ADx and Conversion

If you don't want to change the ports, you don't have to. If you do, simply change the values of httpPort:, httpsPort:, ajpPort:, and serverPort: to the values you want.

Admin User

In this section, you need to enter the credentials of the admin user.

As with the keystore, you need to encrypt the admin password. To do so, open the unzipped package, then open the terminal and run ./encrypt.sh --value mypassword. You should get the encrypted password as a response:

```
VTGEjDxNV17nHqxj/aXrLwAKmksFgUWIht5JZdPIZb5r3yeODUE0v+hz72y4TDD7eZfP9Q==
```

Copy this response (not the one above but the one you get) and paste it into the `password:` property. The file should then look as follows:

```yaml
# ** Admin User **
# Configures the credentials for the default admin user.
# If the user doesn't exist yet, it will be created and the password will be set as specified here.
# If the user already exists, nothing will be done, i.e. its password will NOT be changed!
predefinedComponents:
  ADMIN_USER: !com.braintribe.model.user.User
    # Admin user name
    name: 'admin'
    # Admin user password. Replace "[ENCRYPTED_PASSWORD]" with the encrypted password, e.g. '${decrypt("HMuN/VXo5+L0vVQzuJe7bAOiBmeKzWluP+POb7zjkcLCnzgawUfWmZAIu9eIOfVAzEQn6Q==")}'.
    password: '${decrypt("VTGEjDxNV17nHqxj/aXrLwAKmksFgUWIht5JZdPIZb5r3yeODUE0v+hz72y4TDD7eZfP9Q==")}'
```

System Database

In this section, you need to put the information describing your system database (user name, encrypted password, database driver, database URL) into the properties found under connectionDescriptor:. Other properties (apart from the name) must be left with the default values.:

# ** System Database **
# Configures the default system database connection pool.
  DEFAULT_DB: !com.braintribe.model.deployment.database.pool.HikariCpConnectionPool
    # The external id of the connection pool (don't change!)
    externalId: 'connection.default'
    # The name of the connection pool (don't change!)
    name: 'Default Database Connection'
    # This minimum connection pool size
    minPoolSize: 3
    # This maximum connection pool size
    maxPoolSize: 20
    # Connection settings ( '&systemDatabaseConnection' specifies an anchor, which makes it possible to re-use the connection settings below)
    connectionDescriptor: &systemDatabaseConnection !com.braintribe.model.deployment.database.connector.GenericDatabaseConnectionDescriptor
      # JDBC Driver
      #   Postgres: 'org.postgresql.Driver'
      #   Oracle: 'oracle.jdbc.OracleDriver'
      #   MSSQL: 'com.microsoft.sqlserver.jdbc.SQLServerDriver'
      driver: 'org.postgresql.Driver'
      # JDBC URL
      #   Postgres: 'jdbc:postgresql://localhost:5432/system-db'
      #   Oracle: ' jdbc:oracle:thin:@localhost:1521:orcl12c'
      #   MSSQL: 'jdbc:sqlserver://localhost:5433;databaseName=system-db;'
      url: 'jdbc:postgresql://localhost:5432/your-system-db'
      # Database user name
      user: 'adminDB'
      # Database user password. Replace "[ENCRYPTED_PASSWORD]" with the encrypted password, e.g. '${decrypt("HMuN/VXo5+L0vVQzuJe7bAOiBmeKzWluP+POb7zjkcLCnzgawUfWmZAIu9eIOfVAzEQn6Q==")}'.
      password: '${decrypt("VTGEjDxNV17nHqxj/aXrLwAKmksFgUWIht5JZdPIZb5r3yeODUE0v+hz72y4TDD7eZfP9Q==")}'

driver:

driver: is different depending on the database type. Copy the driver property from the table below:

Databasedriver: value
PostgreSQL"org.postgresql.Driver" (default)
Oracle"oracle.jdbc.OracleDriver"
Oracle 8i"oracle.jdbc.driver.OracleDriver"
MSSQL"com.microsoft.sqlserver.jdbc.SQLServerDriver"
MSSQL JTDS"net.sourceforge.jtds.jdbc.Driver"
MYSQL"com.mysql.jdbc.Driver"
DB2"com.ibm.db2.jdbc.net.DB2Driver"

url:

url: will be different depending on the database type. Use the syntax as explained in the table below:

Databaseurl: syntaxExample
PostgreSQL"jdbc:postgresql://hostname:port/databaseName". Replace hostname with the actual name (for example localhost) port with the database port (for example 5432), and databaseName with the name of the database (for example system-db), then copy-paste into the url: property."jdbc:postgresql://localhost:5432/system-db"
Oracle with service name"jdbc:oracle:thin@hostname:port/serviceName". Replace hostname with the actual name (for example localhost) port with the database port (for example 5432), and serviceName with the database service name TNS alias (for example system-db), then copy-paste into the url: property."jdbc:oracle:thin@localhost:5432/system-db"
Oracle with SID"jdbc:oracle:thin@hostname:port:SID". Replace hostname with the actual name (for example localhost) port with the database port (for example 5432), and SID with the database ID (for example system-db), then copy-paste into the url: property."jdbc:oracle:thin@localhost:5432:system-db"
MSSQL"jdbc:sqlserver://hostname:port;databaseName". Replace hostname with the actual name (for example localhost) port with the database port (for example 5432), and databaseName with the name of the database (for example system-db), then copy-paste into the url: property."jdbc:sqlserver://localhost:5432;system-db"
MYSQL"jdbc:mysql://host:port/databaseName" Replace hostname with the actual name (for example localhost) port with the database port (for example 5432), and databaseName with the name of the database (for example system-db), then copy-paste into the url: property."jdbc:mysql://localhost:5432/system-db"
DB2"jdbc:db2://hostname:port/databaseName". Replace hostname with the actual name (for example localhost) port with the database port (for example 5432), and databaseName with the name of the database (for example system-db), then copy-paste into the url: property."jdbc:db2://localhost:5432/system-db"

user:

Simply enter the user name with access to the database.

password

As with all passwords, you need to encrypt the database user password. To do so, open the unzipped package, then open the terminal and run ./encrypt.sh --value mypassword (.bat on Windows). You should get the encrypted password as a response:

```
VTGEjDxNV17nHqxj/aXrLwAKmksFgUWIht5JZdPIZb5r3yeODUE0v+hz72y4TDD7eZfP9Q==
```

Copy this response and paste it into the password: property.

That's it! You can now proceed to the next section of the configuration file.

Runtime Properties

Platform Settings

The only mandatory setting is the TRIBEFIRE_PUBLIC_SERVICES_URL provides the URL on which this service can be reached. When using multiple ADx Core servers, provide the load balancer URL.

Important: TRIBEFIRE_PUBLIC_SERVICES_URL must be reachable from the outside. Make sure it is not blocked by a firewall.

TRIBEFIRE_IS_CLUSTERED must be set to true if this node is going to be part of a cluster. In this case, don't forget to add it to the list of hosts in AMQ_CLUSTER_NODES - see ActiveMQ Settings.

This is the full list of platform settings as it shows in the YAML property file:

# ** Runtime Properties **
# Runtime properties are used to configure application specific settings. Which properties are available/required depends on the application.
# For the complete list of supported runtime properties refer to the documentation. However, all important/mandatory properties are listed below.
runtimeProperties:
  ##############################################################################
  # Platform Settings
  ##############################################################################
  # This enables support for encrypted passwords in this configuration file (don't change!)
  TRIBEFIRE_SECURED_ENVIRONMENT: 'true'

  # Specifies how long a user session should remain active when there is no activity on the session.
  # After the specified inactive time has passed (i.e. no request with the corresponding session ID has been received by the server),
  # the session is flagged as inactive and consequently removed by a periodic cleanup process.
  # The time span can be specified as a human-readable string, using numbers and the time unit, as in 12h, 30m, 3600s, etc.
  TRIBEFIRE_USER_SESSIONS_MAX_IDLE_TIME: '30m'

  # When this is set to true, the login dialog will offer an option to stay signed-in after a browser restart.
  # If this is set to false, the user session will always be closed when the browser is closed.
  # This is achieved by using a session cookie that stores the user's session ID until the browser is closed.
  TRIBEFIRE_RUNTIME_OFFER_STAYSIGNED: 'true'

  # The public tribefire services URL, i.e. the URL through which clients and other services can reach this service.
  # This is e.g. needed for callbacks, for example when service A invokes an (asynchronous) job on B and passes a callback URL,
  # through which B can notify A when the job is done.
  #
  # In a clustered environment, i.e. multiple nodes, the load balancer URL has to be specified here.
  # If there is only a single node and no proxy or something like that, the URL is usually just
  # 'https://(hostname of this machine):(https port configured above)/tribefire-services'.
  #
  # Make sure that the public URL is reachable from other machines, e.g. verify that configured ports are opened in the firewall.
  TRIBEFIRE_PUBLIC_SERVICES_URL: 'https://[PUBLIC_HOST]:[PUBLIC_PORT]/tribefire-services'

  # Indicates whether or not this node is part of a cluster.
  # (Note that a cluster may also just have a single node, thus this setting can always be enabled.)
  TRIBEFIRE_IS_CLUSTERED: 'true'

  # A comma-separated list of host names (or IP addresses) of the nodes that should form a cluster.
  # Example: 'adx1.example.com,adx2.example.com,adx3.example.com'
  # If there are multiple nodes, these nodes must (!) be behind a load balancer and clients or other services must connect
  # through the respective load balancer URL (specified in TRIBEFIRE_PUBLIC_SERVICES_URL).
  # If there is just a single node, i.e. no cluster, this can be left empty.
  TRIBEFIRE_CLUSTER_NODES: ''

Conversion Settings

If your setup has a remote Conversion service, make sure you configure DOCUMENTS_CONVERSION_TFS_URL, DOCUMENTS_CONVERSION_USERNAME, and DOCUMENTS_CONVERSION_PASSWORD.


##############################################################################
  # Conversion Settings
  ##############################################################################
  # Enables local conversion service. If set to false, a remote conversion service is required (see below).
  CONV_INITIALIZE: 'false'
  # Enables remote conversion service.
  # If enabled the following three properties need to be set as well.
  ADX_DEFAULT_REMOTE_CONVERSION_ENABLED: 'true'
  # The URL of the remote conversion service to be used.
  # If the remote conversion service is clustered, this must be the load balancer URL!
  ADX_DEFAULT_REMOTE_CONVERSION_TFS_URL: 'https://[CONV_HOST]:[CONV_PORT]/tribefire-services'
  # The name of the remote conversion service user. Add the name of the standard conversion user here,
  # i.e. the name set in property CONV_STANDARD_USER_NAME in conversion settings.
  ADX_DEFAULT_REMOTE_CONVERSION_USERNAME: 'tf-conversion'
  # The password of the remote conversion service user. Add the password of the standard conversion user here,
  # i.e. the password set in property CONV_STANDARD_USER_PASSWORD in conversion settings.
  ADX_DEFAULT_REMOTE_CONVERSION_PASSWORD: '${decrypt("[ENCRYPTED_PASSWORD]")}'

Explanation of each setting is here:

  • DOCUMENTS_CONVERSION_TFS_URL: - provide the hostname and port of the conversion service installed previously. When using multiple conversion servers, provide the load balancer URL.

    Important: DOCUMENTS_CONVERSION_TFS_URL: must be reachable from the outside. Make sure it is not blocked by a firewall.

  • DOCUMENTS_CONVERSION_USERNAME: - provide a user name set up on the conversion service. Typically it is the default user set during conversion installation in CONV_STANDARD_USER_NAME.

  • DOCUMENTS_CONVERSION_PASSWORD: provide the encrypted password of the above user.

Installation

Congratulations, you are now ready to install ADx!

  1. Go to the directory where you unzipped the package. Open adx-deployment-package.

  2. Open the terminal and run ./install.sh (./install.bat on Windows). If your installation settings file is not in the default location, adapt the paths and/or names accordingly (for example /install.sh --settings /path/to/installation-settings.yaml --environment /path/to/environment.sh.

    If the installation failed, quote the full version of the package (including the -p suffix if it's in your package name) to the support team.

  3. ADx should now be installed in the directory specified in the configuration file. To start it, enter /runtime/host/bin in the installation directory, then run ./tribefire-console-start.sh (./tribefire-console-start.bat on Windows). Alternatively, you can start the server as a Linux service.

To stop the service, run ./tribefire-console-stop.sh (./tribefire-console-stop.bat on Windows).

After start-up, ADx will be available in your browser under the host and port you configured (for example http://localhost:8080). Enjoy using ADx!

Post-installation

Having installed ADx, do the following to verify that the functionality works as expected:

  1. Run the platform health check to verify that the server is accessible and ADx is responding. In the folder where you unzipped the deployment package, open the terminal and run the ./check-health.sh --url http://localhost:8080 (./check-health.bat on Windows) command.

    Change the command accordingly so that it's referring to your server, port, and transfer protocol (http/https). You can reference the environment variable script while running health check by adding --environment ../environment.sh (.bat on Windows) to the command (adapt the path accordingly if you saved your environment script elsewhere).

    After the health check has finished (it may take a few minutes), there are two possible outcomes:

    • Successfully completed health check. Deployed services are available.
    • Health check failed! For more information see health-check-result.json and/or run health check directly via http://localhost:8080/tribefire-services/healthz
  2. Log in to ADx.

  3. Open the landing page, then click Explore under ADx Admin Access (available under Service Domains). Admin Access opens.

  4. Create a new repository. If you used properties related to default repository settings upon installation, your default values should be already configured:

  5. Run a connection health check on the repository (click Health in the bottom menu, then Connection Check). The resulting report should be all green.

  6. Synchronize the repository (click Synchronize in the bottom menu).

  7. Activate the repository (click Activate in the bottom menu). This action enables the Content Access and brings all endpoints online.

  8. Run a deep health check on the repository (click Health in the bottom menu, then Deep Check). The resulting report should be all green. If the report is OK, you can now start using ADx!

What's next?

Having installed and deployed ADx, you can start using the provided functionality. After you log in, you can find all of your repositories (and their APIs) in the landing page, under Operations. Click Explore to open a repository. See the following resources for more information:

You can always run a number of health checks to make sure everything is running smoothly. For more information, see Running Conversion and Platform Health Checks. If you want to run checks on legacy endpoints, see Running Deep Health Checks on Legacy Endpoints.