logoBack to home screen

ADx Installation Advanced Configuration

Leaving the following settings to their default values will not prevent you from installing and running the ADx.

HTTPS/SSL

HTTPS/SSL settings control how ADx should be accessed once installed. If you don't need HTTPS access, you can skip this section entirely, and move on to Resources. Otherwise, follow the below procedure.

Initially, this section looks as follows:

# ** HTTPS/SSL **
# Whether or not to enforce HTTPS, i.e. redirect HTTP to HTTPS
enforceHttps: false

# The path to the SSL keystore file, PKCS 12 format (see https://en.wikipedia.org/wiki/PKCS_12).
# If not set, the default keystore with a self-signed certificate will be used.
#sslKeystoreFile: !com.braintribe.model.resource.FileResource
#  path: '/path/to/keystore.p12'

# One can use openssl to generate a (self signed) keystore file:
#   openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout privateKey.key -out certificate.crt
#   openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -export -in certificate.crt -inkey privateKey.key -out keystore.pkcs12 -name 'tribefire'
# For more information see https://www.openssl.org/.

# The password for the keystore file (see above). Replace "[ENCRYPTED_PASSWORD]" with the encrypted password, e.g. '${decrypt("HMuN/VXo5+L0vVQzuJe7bAOiBmeKzWluP+POb7zjkcLCnzgawUfWmZAIu9eIOfVAzEQn6Q==")}'.
#sslKeystorePassword: '${decrypt("[ENCRYPTED_PASSWORD]")}'

# If the keystore file was generated without a password, set the password to empty string.
#sslKeystorePassword: ''
  1. Set enforceHttps: to true:

    # Whether or not to enforce HTTPS, i.e. redirect HTTP to HTTPS
    enforceHttps: true
    
  2. Now, you can either skip the path section entirely to use the default keystore, or generate your own self-signed keystore file. This tutorial shows the second option. If you don't want to do it, move on to Resources.

    1. Remove the # comment marks in front of sslKeystoreFile: and path:. You should get the following result:

      # If not set, the default keystore with a self-signed certificate will be used.
      sslKeystoreFile: !com.braintribe.model.resource.FileResource
       path: '/path/to/keystore.p12'
      
      
    2. Now we need to generate the keystore. First, let's create a folder where it will be stored. In this tutorial, it's the SSL folder under Home/Documents.

    3. Open the newly created folder and run the terminal from it.

    4. Execute $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout privateKey.key -out certificate.crt. You will be prompted for some data - this is expected. This command generates the private key and certificate:

      We will need those files to create the keystore.

    5. Execute openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -export -in certificate.crt -inkey privateKey.key -out keystore.pkcs12 -name "tribefire". This generates the keystore.pkcs12 file. You will be prompted for password in the process - remember it, you will need it later!

    6. Now that you have the keystore, you can add its path to the configuration file:

      # If not set, the default keystore with a self-signed certificate will be used.
      sslKeystoreFile: !com.braintribe.model.resource.FileResource
        path: `/home/user/Documents/SSL/keystore.p12`
      
    7. Finally, we need to encrypt the keystore password in order to provide it in the configuration file. Let's go back to the installation directory, where you will find the encrypt.sh script.

    8. 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 sslKeystorePassword property, in place of [ENCRYPTED_PASSWORD]:

      sslKeystorePassword: `${decrypt("VTGEjDxNV17nHqxj/aXrLwAKmksFgUWIht5JZdPIZb5r3yeODUE0v+hz72y4TDD7eZfP9Q==")}`
      

That's it - you have now configured HTTPS access for ADx. When installed with those setting, it should always redirect to HTTPS, using the keystore you generated.

HTTP Security

You can edit the trustedDomain value to restrict access to this node from other domains. By default, cross-domain access is permitted for all hosts.

# ** HTTP Security **
# The Cross Domain Policy is used to define cross-domain related security settings.
# For example, if there are other web applications which want to embed this application's content in an iframe, e.g. the Web Reader,
# these applications have to be in the trustedDomain configured below. Examples:
#   '*' - permit cross-domain access from any host
#   '*.example.com' - permit cross-domain access from respective hosts on example.com domain
#   '' - disable cross-domain access
# Note that this setting has nothing to do with normal clients connecting to this application or other applications connecting via API.
# For further information read e.g. the HTTP Security section at https://developer.mozilla.org/en-US/docs/Web/HTTP.
crossDomainPolicy: !com.braintribe.model.platform.setup.api.cdp.SimpleCrossDomainPolicy
  trustedDomain: '*'

Resources

Unless instructed otherwise, you can simply use the default JVM values as shown below:

# ** Resources **
# The maximum number of connections (or -1 for no limit)
maxConnections: -1
# The maximum number of request worker threads.
maxThreads: 4000

That's it! You can move on to the next section.

Logging

In this section, you need to provide the directory for the log files. The easiest course of action is to use the default settings:

# ** Logging **
# The path of the directory where log files will be written to. '&logFilesDir' specifies an anchor, which makes it possible to reference the value below, see setting 'checkWriteAccessForDirs'.
# Relative paths are supported and will be resolved relative to the installation path (see setting 'installationPath).
# Example: if installation path is '/opt/braintribe/adx/tribefire', then '../logs' means '/opt/braintribe/adx/logs'.
logFilesDir: &logFilesDir '../logs'

# Log level for console output. Examples: SEVERE,WARNING,INFO,FINE,FINEST
consoleLogLevel: 'INFO'

# Log level for file output. Examples: SEVERE,WARNING,INFO,FINE,FINEST
logFilesLogLevel: 'FINE'

# Enables log rotation based on file size (in bytes). If the specified maximum is exceeded, the current log file will be archived and a new one will be created.
logFilesMaxSize: 15000000

# Enables log rotation based on a Cron expression.
# Note that in addition to the standard fields also field [second] is supported. It works like [minute].
# Thus supported fields are: [second], [minute], [hour], [day of the month], [month], [day of the week]
# For more information see https://en.wikipedia.org/wiki/Cron.

# Rotate every day at midnight
logFilesCronRotate: '0 0 0 * * *'
# Rotate every hour
#logFilesCronRotate: '0 0 * * * *'

# Maximum number of archived log files (see also log rotation settings above). If the maximum is exceeded, the oldest archived log files gets deleted.
logFilesMaxCount: 10

That's it! You can move on to the next section.

Temporary files

Similarly as with the logs, you can simply use the default location for temporary files:

# ** Temporary Files **
# The path of the directory where temporary files will be written to. '&tempDir' specifies an anchor, which makes it possible to reference the value below, see setting 'checkWriteAccessForDirs'.
# Relative paths are supported and will be resolved relative to the installation path (see setting 'installationPath).
# Example: if installation path is '/opt/braintribe/adx/tribefire', then '../temp' means '/opt/braintribe/adx/temp'.
tempDir: &tempDir '../temp'

That's it! You can move on to the next section.

ActiveMQ Settings

Each node provides embedded ActiveMQ communication. You don't need to change these settings if you don't change anything in ActiveMQ runtime properties. If you did, adapt hostAddress accordingly.

# ** ActiveMQ Settings **
# Configures the ActiveMQ connection. Since each node provides an embedded ActiveMQ server, the URL just points to localhost.
# Unless a custom ActiveMQ server port is configured below (see AMQ_SERVER_PORT), there is no need to change these settings.
  MQ: !com.braintribe.model.messaging.jms.JmsActiveMqConnection
    name: 'ActiveMQ Connection'
    hostAddress: 'tcp://localhost:61616'

Connection Pools

As stated by the configuration file comments, you don't need to change these properties unless instructed otherwise.

Project Settings

Project descriptor available in this section defines the name and the displayed name of the tomcat service. You don't need to change these settings unless instructed otherwise.

# ** Project Settings **
# Configures the project / product name. Usually these settings don't have to be changed. The names are e.g. used as service name,
# when starting Tomcat as a service. See 'tomcatServiceDescriptor' below.
projectDescriptor:
  name: 'adx'
  displayName: 'Agile Documents Platform'

Tomcat Settings

Tomcat service descriptor available in this section defines the name of the service user when you run the application as a Tomcat service. You don't need to change these settings unless instructed otherwise.

# ** Tomcat Service **
# One can use script /tribefire/runtime/host/bin/tribefire-service.sh to run the application as a Tomcat service.
# In that case one can configure the service user here. Service name, by default, will be based on project name, see 'projectDescriptor' above.
# For further information about running Tomcat as a service read the documentation.
tomcatServiceDescriptor:
  # Specifies the name of the service user
  user: '[SERVICE_USER]'

Runtime Properties - ActiveMQ Settings

Enter a full list of ADx nodes in AMQ_CLUSTER_NODES. Optionally, you can also set up Multicast communication. If you change the host or port, you also need to adapt the host address in previous ActiveMQ Settings

##############################################################################
  # ActiveMQ Settings
  ##############################################################################
  # Each node provides its own, embedded messaging service (based on ActiveMQ).
  # The messaging service enables nodes to communicate with each other, e.g. to send notification events from one node to all others.

  # The ActiveMQ server port.
  AMQ_SERVER_PORT: '61616'

  # A comma-separated list of host names (or IP addresses) of the nodes that should form a cluster.
  # Each address may also include a port (separated by a colon). If no port is specified, it defaults to the port configured in setting AMQ_SERVER_PORT.
  # Example: 'adx1.example.com,adx2.example.com,adx3.example.com:61617'
  # By default this setting just points to TRIBEFIRE_CLUSTER_NODES and usually there is no need to change this.
  # Only exception is when one runs multiple instances on the same host (with different ActiveMQ ports).
  AMQ_CLUSTER_NODES: '${TRIBEFIRE_CLUSTER_NODES}'

  # As an alternative to setting AMQ_CLUSTER_NODES ActiveMQ also supports connection to remote nodes via multicast transport.
  # This feature is disabled by default. Before enabling it ensure that the network (and firewalls, if any) permit multicasts on port 6155.
  #
  # The group name shared between all adx cluster nodes. Setting this value activates the multicast transport.
  #AMQ_DISCOVERY_MULTICAST_GROUP: 'adx'
  # The network interface through which multicasts are sent, e.g. 'eth0'.
  #AMQ_DISCOVERY_MULTICAST_NETWORK_INTERFACE: '[NETWORK_INTERFACE]'

Runtime Properties - Fulltext Settings

Settings related to elastic-search configuration.

##############################################################################
# Fulltext Settings
##############################################################################
# Whether an elasticsearch service should be started together with this ADx installation.
ELASTIC_RUN_SERVICE: 'true'
# Whether to enable the default elasticsearch access.
#ELASTIC_CREATE_DEMO_ACCESS: 'false'
# The base directory to store elasticsearch indices.
# In clustered environments this must point to a shared file system and all nodes must use the same folder.
ELASTIC_SERVICE_DATA_PATH: '${TRIBEFIRE_INSTALLATION_ROOT_DIR}/../elastic'
# The elasticsearch service port (used for intercommunication between the nodes).
ELASTIC_PORT: '9300'
# A comma-separated list of host names (or IP addresses) of the nodes that should form a cluster.
# Each address may also include a port (separated by a colon). If no port is specified, it defaults to the port configured in setting ELASTIC_PORT.
# Example: 'adx1.example.com,adx2.example.com,adx3.example.com:9301'
# By default this setting just points to TRIBEFIRE_CLUSTER_NODES and usually there is no need to change this.
# Only exception is when one runs multiple instances on the same host (with different elasticsearch ports).
ELASTIC_CLUSTER_NODES: '${TRIBEFIRE_CLUSTER_NODES}'
# Whether or not to enable fulltext indexing by default when creating new repository.
ADX_DEFAULT_REPOSITORY_FULLTEXT_ENABLED: 'true'

Repository Settings

See Default Repository Settings

Runtime Properties - Retry Mechanism Settings

These properties allow you to override the default retry mechanism settings. If you don't change them, retries will simply run based on the below settings.

##############################################################################
# ADx Conversion Jobs Retry Settings
# This mechanism periodically checks for stale ADx jobs and revives them.
# (The settings below are for now global settings, which means they can't be
#  configured on repository level via the administration UI yet.)
##############################################################################
# The interval between checks for stale ADx Content representation jobs.
# Allowed units: year (y), month (m), day (d), hour (h), minute (min), second (s)
ADX_DEFAULT_JOB_REVIVE_WORKER_CHECK_INTERVAL: '5 min'
# Maximum inactivity period of a stale job before a retry.
# Allowed units: year (y), month (m), day (d), hour (h), minute (min), second (s)
ADX_DEFAULT_JOB_REVIVE_WORKER_MAX_INACTIVITY_BEFORE_RETRY: '60 min'
# The maximum number of retries for a single job. If this number is reached,
# there will be no further retries and the problem has to be analyzed and fixed manually.
ADX_DEFAULT_JOB_REVIVE_WORKER_MAX_TRIES: '3'