Configuring HCL Traveler on Docker

This topic describes Traveler specific configuration items for Docker.

Traveler on Docker is a Domino on Docker server that has Traveler installed. Domino configuration needs to be completed after installation. There are several options for performing the initial Domino configuration. The method you choose affects how you perform the Traveler configuration.

Remote setup - Deploying a new Domino server on Docker describes how to configure a Domino on Docker image using a remote Domino Admin client to perform the setup. You create a temporary docker container to perform the setup, then create a second docker container to run the configured Domino.
One-touch Domino config with system environment variables - Invoking one-touch Domino setup with system environment variables on Docker describes how you can configure and run Domino in one step. The items available to be configured are limited, but are sufficient for setting up a Traveler server.
One-touch Domino config with a JSON file - Invoking one-touch Domino setup with parameters in a JSON file on Docker describes the steps for defining and using a JSON file containing the Domino configuration items.

Be aware that some of the Domino parameters contain passwords. If you are using Domino one-touch config and want to avoid saving the passwords in the config files or environment variables, the Domino one-touch config process provides a secure mechanism to do that. For more information, see Specifying passwords indirectly.

The following sections describe the Traveler items that need to be set in addition to the base Domino configuration items:

Mapping Traveler ports into the Docker image

The docker run command maps ports from the docker host system into the hosted docker image so that applications running inside the image that listen on those ports can receive inbound connection requests. Traveler requires these ports to be mapped, in addition to the ports already mapped for Domino server use:

Ports          Usage

-------------- ------------------------------------

80, 443        HTTP(S) for inbound requests from mobile devices

50125,50126    Traveler inter-process communication

Configuring Domino to start Traveler automatically when the server starts

The Traveler on Docker image has an initialization script that is executed when the image is run that appends TRAVELER to the ServerTasks entry in the notes.ini file if it is not already there. However, the ServerTasks entry does not exist until after the Domino server has been configured. If you configure the Domino server using remote setup, the initialization script runs when the second docker container is started, so Traveler starts automatically.

However, if you use one-touch Domino configuration, it may not start Traveler automatically the first time Domino starts. You can issue the load traveler command in the Domino console command prompt to cause it to start, or stop and restart the docker image to allow the initialization script to update the ServerTasks entry and cause Traveler to load.

To allow Traveler to start during the first run, you can preconfigure Domino to append TRAVELER to the ServerTasks list as part of one-touch config. Use the following system environment variable:

SERVERSETUP_SERVER_ADDITIONALSERVERTASKS=Traveler

or the following JSON key:value pair:

"serverSetup": {
        "server": {
               "additionalServerTasks":"Traveler"
        }
}

This causes Domino to append Traveler to the ServerTasks list before initialization runs.

Using environment variables to set NTS_ settings in notes.ini

The initialization script that runs during the docker image startup includes logic that sets NTS_ settings in notes.ini that would normally be added by the Traveler installer (if the installer was being run on a pre-configured Domino system).

The script also has logic that detects environment variables that are defined in the image and start with NTS_. For each variable, it sets that value in notes.ini if the setting is not already specified in the notes.ini file. You can pass these NTS_ environment variables into the docker image by coding them on --env parameters on the docker run command, or by putting them in a text file and passing that on the –-env-file parameter on docker run. If you are using one-touch Domino config passing system environment variables, you can include them in the file that holds the one-touch config system environment variables. For more information see Preparing input parameters through system environment variables.

This mechanism can be used to override default Traveler settings. For example, by default the script sets NTS_AUTOSTART_HTTP=true in notes.ini because that is the recommended setting for Traveler servers. However, as described in Starting and stopping the server, you may want to set environment variable NTS_AUTOSTART_HTTP=false in the Docker image if you need the HTTP task to continue to run in your Domino Docker image even when Traveler is stopped.

Setting the external URL for the Traveler server

Setting the external server URL describes how to set the Traveler server’s URL that mobile devices use to connect to Traveler. It also includes a description of the JSON to be used to set the URL in the Domino server document if you are using one-touch Domino config with a JSON file. For Traveler on Docker images, you also have the option of passing in environment variable NTS_EXTERNAL_URL. See the following example:

NTS_EXTERNAL_URL=https://hostname.example.com:1234/traveler

This is important for Docker because the hostname of the Docker image might not be externally visible to mobile devices. Instead, the hostname or IP address of the node that hosts the Docker image might need to be used.

Configuring an enterprise database server

By default, the Traveler on Docker node will use a Derby database for tracking. If you want to configure Traveler on Docker to use an enterprise database, as described in Configuring HCL Traveler for enterprise database, you need to bring up a docker container with entry point /bin/bash in order to run the travelerUtil program, and to run docker copy to copy the JDBC driver into the notesdata volume for subsequent use by the Domino container.

Alternatively, you can set the enterprise database configuration using NTS_DB* environment variables. The JDBC driver must still be passed by using docker copy if configuring this way for a non-MySQL database server. MySQL database servers have the additional option of setting NTS_DBPATH=<download URL> of the correct JDBC driver.

Upgrading a Traveler on Docker image

HCL periodically issues new Docker images containing the latest Domino and/or Traveler fixes. The process for starting a new Traveler on Docker image with a previously configured Docker /local/notesdata volume is simpler because the initial Domino configuration has already been done.

To ensure that the Traveler files associated with the new code level are properly installed into the existing volume, add parameter --update to the docker run command the first time you start the new image with the existing Docker /local/notesdata volume. For more information, see Upgrading a containerized Domino server in the Domino documentation.