logoBack to home screen

Installing Conversion Service

To install the Conversion service, you must perform the following steps:

  1. Make sure all prerequisites are met. See Prerequisites.
  2. Prepare the necessary files for installation. See Preparing Necessary Files for Installation.
  3. Configure the mandatory settings in the installation-settings.yaml. See Mandatory Configuration.
  4. Configure the advanced settings in the installation-setting.yaml. This step is optional. See Advanced Configuration.
  5. Install Conversion. See Installing Conversion.
  6. Start up the Tomcat server for the Conversion service. See Starting Up Conversion.
  7. Run health checks to test your installation. See Running Conversion Health Checks.

Prerequisites

  • At least one running database - you will need the URL (host name and port) and user credentials. Database setup must be provided by your organization. See Verifying Database Connection.
  • See a full list of general prerequisites at prerequisites first.

Preparing Necessary Files for Installation

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

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

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

    On Linux:

    mkdir ../additional-libraries
    
    mkdir ../license
    
    # Copy and edit 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 and edit 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 conversion-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 the conversion service 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 (simply copy and paste the driver .jar file):

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 look like 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/conversion/tribefire', the (default) log files directory is '/opt/braintribe/conversion/logs'.
installationPath: '/opt/braintribe/conversion/tribefire'

Ports

Important! If you are installing both Conversion and ADx core on the same machine, make sure all ports (including Active MQ port) for Conversion are different from the ones in ADx core configuration file.

The ports determine the URL under which the conversion service 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

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

That's it - let's move on to the next part.

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 must be left with the default values. See the example below.

# ** 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-name'
      # Database user name
      user: 'example-db-user'
      # 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. 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.

Conversion Database

The configuration of the conversion database is exactly the same as described for System Database - simply carry out the same procedure in the conversion section of the file, providing data of the conversion database in the process.

Platform Settings

The only mandatory platform setting is the TRIBEFIRE_PUBLIC_SERVICES_URL runtime property. It has the value of https://[PUBLIC_HOST]:[PUBLIC_PORT]/tribefire-services. For example, when you install Conversion on your local machine, the URL would be something like https://localhost:8080/tribefire-services

Installing Conversion

Congratulations, now you're done configuring the file. Remember to save it (you can change the name and location, but you don't have to), then proceed to installation.

If you're on Windows, use the .bat scripts instead of the .sh scripts mentioned below. Their functionality is exactly the same.

  1. Go to the directory where you unzipped the package.

  2. Open the terminal and run ./install.sh (./install.bat on Windows). This command doesn't require adapting, provided you prepared the installation-setting.yaml and environment.sh as described. Otherwise, you need to 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 fails, please quote the full version of the package (with the -p suffix) to the support team.

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

  4. Run the health check on the installed service.

  5. Open the URL entered as TRIBEFIRE_PUBLIC_SERVICES_URL: to manually verify that it works.

  6. You're done!

    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.

Starting Up Conversion

To start the service, enter tribefire/runtime/host/bin in the installation directory, then run ./tribefire-console-start.sh (.bat on Windows). Alternatively, you can start the server as a Linux service.

Running Conversion Health Checks

After start-up, conversion service will be available in your browser under the host and port you configured (for example http://localhost:8080). You can also run a number of health checks to make sure everything is running smoothly. For more information, see Running Conversion and Platform Health Checks. For checks on legacy features, see Running Deep Health Checks on Legacy Endpoints.

Having installed and deployed the conversion service locally, you can now do the same for ADx Core. See Installing ADx Core for details.