Installing Conversion Service
This page describes how to install Conversion Service on a prepared server.
Before you begin
- Prepare for the installation of Document.One system as it is described in Preparing for installation.
- Prepare files necessary for installation and configuration of Conversion Service. See Prepare files necessary for installation.
- Obtain the following database connection details: db URL, host, port, and user credentials.
- Set up JAVA environment variables. See Setting up JAVA environment variables.
- Create the SSL keystore password if you plan to enable HTTPS connection for the Conversion Service. For details, see Generating SSL keystore.
- Prepare a file with encrypted passwords. See Encrypting system passwords.
Installation process overview
To install the Conversion service, you must perform the following steps:
- Configure the mandatory settings in the
installation-settings.yaml
. - Configure advanced settings in the
installation-setting.yaml
. This step is optional. - Install the Conversion Service.
- Run health checks to test your installation.
Task 1: Configure mandatory settings
On the D1 installation server, open the installation-settings.yaml
file in a text editor of your choice, and edit the following sections:
Section / Parameters | Description | Notes | Configuration reference |
---|---|---|---|
Installation path:
| You can either use the default path or set another value for the installation directory of your choice. All relative paths used in the configuration file are resolved from the installation directory. | If you set other than the default value, you need to provide an absolute path in the configuration file. | Installation path example |
Ports:
| Ports determine the URL under which the Conversion service will be available when installed. For example, You can use the default ports, or adjust port values as required. | If you are installing Conversion Service and D1 on the same server, you must set unique values for each port. This note is also applicable to the | Ports |
Admin user:
| In this section, you need to enter the credentials of the admin user. | You must encrypt the password of the admin user before entering it into the | Admin user |
System database:
The rest of the properties must be left with the default values. | You need to put the information describing your system database into the properties found under the
PostgreSQL | You must encrypt the password of the admin user before entering it into the | System database |
Conversion database:
The rest of the properties must be left with the default values. | The configuration of the conversion database is exactly the same as described for the System database. Carry out the same procedure in the conversion section of the file, providing data of the conversion database in the process. | You must encrypt the password of the admin user before entering it into the | System database |
Platform settings: TRIBEFIRE_PUBLIC_SERVICES_URL is the only mandatory setting. | It has the following format: For example, when you install Conversion service on your local machine, the URL would be something like |
When you have completed configuring the mandatory settings in your configuration file, you can optionally configure advanced settings described in Task 2 section. If you do not need to configure advanced settings, you can skip this step and proceed with Task 3.
You must save the changes to the file when you are done configuring the file.
Task 2: Configure advanced settings
If you are installing a production system (deployment use case 3) or a Dev/Test environment (deployment use case 2), we recommend that you configure advanced settings.
If you installing a sandbox environment (deployment 1 use case), then configuring advanced settings can be skipped.
Leaving the advanced settings to their default values will not prevent you from installing and running the Conversion Service.
Section / Parameters | Description | Notes | Configuration reference |
---|---|---|---|
HTTPS/SSL:
| HTTPS/SSL settings control how the conversion service should be accessed once installed. Enable the following configuration:
If you plan to use the default keystore, then skip the rest of the steps. The rest of the configuration is needed only if you want to use the self-signed keystore. That is it - you have now configured HTTPS access for the Conversion Service. When installed with those setting, it should always redirect to HTTPS, using the keystore that you generated. | If you do not need HTTPS access, you can skip this section entirely. | HTTPS/ SSL |
HTTP Security:
| You can edit the | By default, cross-domain access is permitted for all hosts. Leave this configuration unchanged if you want to enable the default behavior. | HTTP Security |
Resources:
| Unless instructed otherwise, you can simply use the default JVM values. | N/a | Resources |
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 for the rest of the settings. | N/a | Logging |
Temporary Files:
| In this section, you set the directory for the temporary files. The easiest course of action is to use the default settings for the rest of the settings. | N/a | Temporary files |
ActiveMQ Settings:
| Each node provides embedded ActiveMQ communication. Leave the predefined configuration unchanged. You need to change the | N/a | ActiveMQ settings |
Connection pools | As stated by the configuration file comments, you do not need to change these properties unless instructed otherwise. | N/a | N/a |
Project settings | Project descriptor available in this section defines the name and the displayed name of the Tomcat service. You do not need to change these settings unless instructed otherwise. | N/a | |
Tomcat Service | Tomcat service descriptor available in this section defines the name of the service user when you run the application as a Tomcat service. You do not need to change these settings unless instructed otherwise. | N/a | |
Platform runtime settings:
| Conversion is powered by the Tribefire platform, configured via the platform settings.
|
In a case of the clustered deployment, you must also add the node URL to the list of hosts in the | |
ActiveMQ runtime settings:
| Enter a full list of Conversion nodes in the Optionally, you can also set up the multicast communication. | If you change the host or port, you also need to adapt the | |
Conversion Service runtime settings | These setting control the storage type and location for conversion files as well as the default user credentials on this conversion node. Change these settings as required by your organization. | N/a |
You must save the changes to the file when you are done configuring the file.
Task 3: Install Conversion Service
When you have completed editing the installation-settings.yaml
file, you can install the Conversion Service.
Go to the directory where you unzipped the installation package.
Open the terminal and run the following command:
On Windows On Linux Notes ./install.bat
./install.sh
This command does not need to be adapted, provided that you prepared the
installation-setting.yaml
andenvironment.sh
as described in Setting up JAVA environment variables.If you have not prepared the
environment.sh
script, then you need to adapt the command with the corresponding paths and/or names. For example:/install.sh --settings /path/to/installation-settings.yaml --environment /path/to/environment.sh.
Conversion Service should now be installed in the directory specified in the configuration file.
Start the service as follows:
a. From the installation directory, go to the
tribefire/runtime/host/bin
.b. Run the following command:
On Windows On Linux Notes ./tribefire-console-start.bat
./tribefire-console-start.sh
Alternatively, you can start the server as a Linux service. When the Conversion Service starts, verify that it is accessible. In a browser window enter the URL that you set for the
TRIBEFIRE_PUBLIC_SERVICES_URL
parameter (for example,http://localhost:8080
).
If the installation fails, please quote the full version of the package (including the -p
suffix if it is in your package name) to the support team.
Task 4: Run Conversion Service health checks
To make sure everything is running smoothly, you can run a number of health checks.
For detailed information about the available health checks, see Running Conversion and platform health checks. For checks on legacy features, see Running deep health checks on legacy endpoints.
Conversion Service configuration file reference
Installation path
# ** 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
# ** 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
Admin user
# ** 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
# ** 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==")}'
HTTPS/SSL
# ** 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: ''
HTTP Security
# ** 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
# ** Resources **
# The maximum number of connections (or -1 for no limit)
maxConnections: -1
# The maximum number of request worker threads.
maxThreads: 4000
Logging
# ** 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
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'
ActiveMQ settings
# ** 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"
Project settings
# ** Project Settings **
# Configures the project / product name. Usually these settings don't have to be changed. They names are e.g. used for Tomcat service name, see below.
projectDescriptor:
name: "conversion"
displayName: "Conversion"
Tomcat settings
# ** Tomcat Service **
# One can use script /tribefire/runtime/host/bin/tribefire-service.sh to run the application as a Tomcat service.
tomcatServiceDescriptor:
# Specifies the name of the service user
user: "service-user"
Platform runtime settings
##############################################################################
# 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 many cases this settings can just be set to "https://(hostname of this machine):(https port configured above)/tribefire-services".
# A typical use case where the URL is different, is a clustered service, i.e. multiple nodes behind a load balancer.
# In that case the load balancer URL has to be specified here.
#
# Make sure that this 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.
# (If it is, also ActiveMQ settings must be configured, see above.)
TRIBEFIRE_IS_CLUSTERED: "false"
The configuration file does not include some of the properties that you can additionally use. To enable advanced configuration, see Advanced properties for Tribefire platform runtime.
ActiveMQ runtime 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 ActiveMQ 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".
AMQ_CLUSTER_NODES: "localhost"
# 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]"
The configuration file does not include some of the properties that you can additionally use. To enable advanced configuration, see Advanced properties for ActiveMQ runtime runtime.
Conversion Service runtime settings
##############################################################################
# Conversion Settings
##############################################################################
# Configures conversion services to use the conversion database configured above (don't change!)
CONV_DB_EXISTING_EXTERNAL_ID: "connection.conversion"
# Specifies whether to store conversion resources on file system (-> "fs") or in the database (-> "db").
# Note that this only affects storage of files. Metadata is always stored in the database.
CONV_STORAGE_TYPE: "fs"
# If conversion resources are stored on the file system (see above), this setting points to the folder where resources are stored.
# In clustered environments this must point to a shared file system and all nodes must use the same folder.
CONV_STORAGE_FOLDER: &convStorageFolder "${TRIBEFIRE_INSTALLATION_ROOT_DIR}/../conversion-resources"
# The name of the standard conversion user. This is the user to be used to send conversion requests (e.g. from ADx). This user does not have the admin role.
CONV_STANDARD_USER_NAME: "tf-conversion"
# The password of the standard conversion user (see above). If this property is not set, password will be 'cortex'.
CONV_STANDARD_USER_PASSWORD: "\${decrypt('[ENCRYPTED_PASSWORD]')}"
# The maximum age of a conversion job in the access. This only refers to jobs that have not been updated for this amount of time (in ms).
#CONV_MAX_AGE: "86400000" # 1 day
# The maximum allowed file size (in bytes) of an input resource.
#CONV_MAX_INPUT_FILE_SIZE: "157286400" # 150 MB
# The interval (in ms) how often the system should check for jobs that reached their end of life or should be removed.
#CONV_CHECK_INTERVAL: "600000" # 10 minutes
# The number of parallel worker threads. If this value is less than 1, the number will be computed based on available CPU cores and memory.
#CONV_WORKER_THREADS: "0"
##############################################################################
# Conversion Retry Settings
# This mechanism periodically checks for stale jobs and revives them.
##############################################################################
# The interval (in ms) of the Job Scheduler checking for stale jobs.
CONV_JOB_SCHEDULER_INTERVAL: "300000" # 5 minutes
# The maximum interval of inactivity before a job gets restarted.
CONV_MAX_INACTIVITY_BEFORE_RETRY: "3600000" # 60 minutes
# 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.
CONV_MAX_RETRIES: "3"
##############################################################################
# Conversion Restriction Settings
# These settings define limits that job input files must not break.
# If these limits are broken, the job fails automatically to avoid overloading.
##############################################################################
# Maximum size of an individual input file (in bytes) of a job.
# CONV_MAX_INPUT_FILE_SIZE: "524288000" # 500 MB
# Maximum total file size of all input files (in bytes) of a job.
# CONV_MAX_TOTAL_INPUT_FILE_SIZE: "2147483648" # 2 GB
# Maximum number of input files of a job.
# CONV_MAX_NUMBER_OF_INPUT_FILES: "100"
# Maximum number of objects in a PDF-to-image operation, counted from all pages.
# CONV_PDF_TO_IMAGE_MAX_NUMBER_OF_OBJECTS: "10000000" # ten million
# Maximum number of objects per page in a PDF-to-image operation.
# CONV_PDF_TO_IMAGE_MAX_NUMBER_OF_OBJECTS_PER_PAGE: "1000000" # one million
# Maximum number of pages in a PDF-to-image operation
# CONV_PDF_TO_IMAGE_MAX_NUMBER_OF_PAGES: "10000"
The configuration file does not include some of the properties that you can additionally use. To enable advanced configuration, see Advanced properties for Conversion Service runtime.
Having installed and deployed the Conversion Service, you can now proceed with the installation of D1. See Installing D1.