Configuring HCL Traveler on Docker examples

Example 1: Standalone Domino with Traveler and iNotes configuration

The following example contains the commands to start a standalone Domino mail server with iNotes for web mail access and Traveler for mobile mail access. In this example, the server configuration is performed using one-touch Domino setup passing system environment variables.

iNotes requires HTTP, so the HTTP task is added to the ServerTasks list, in addition to Traveler. Furthermore, HTTP must remain active even if Traveler is brought down, so NTS_AUTOSTART_HTTP is set to false. In this example, the external URL is set by passing the NTS_EXTERNAL_URL into the notes.ini file.

The following list contains the system environment variables to be passed in to the docker run command:

SERVERSETUP_SERVER_TYPE=first 
SERVERSETUP_ADMIN_FIRSTNAME=Joe 
SERVERSETUP_ADMIN_LASTNAME=administrator 
SERVERSETUP_ADMIN_PASSWORD=password 
SERVERSETUP_ADMIN_IDFILEPATH=admin.id 
SERVERSETUP_ORG_ORGNAME=Example 
SERVERSETUP_ORG_CERTIFIERPASSWORD=password 
SERVERSETUP_NETWORK_HOSTNAME=dommail.example.com 
SERVERSETUP_SERVER_DOMAINNAME=Example 
SERVERSETUP_SERVER_NAME=DomMail 
SERVERSETUP_SERVER_ADDITIONALSERVERTASKS=TRAVELER
HTTPNTS_EXTERNAL_URL=https://docker.example.com/traveler 
NTS_AUTOSTART_HTTP=false

The following sample docker run command creates an interactive container that deletes itself upon termination:

docker container run --rm --name dockerExample -it -v dockerSample:/local/notesdata --env-file 
environment.txt --hostname docker.example.com  -p 1352:1352 -p 443:443 -p 80:80 -p 8080:8080  
traveler-docker:V12000_20210316164 --autoconf

The following messages show the initialization and bringup of Traveler:

Preparing for server setup... 
Done. 
Traveler setup checking for required values in /local/notesdata/notes.ini 
Setting NTS_TEMPLATE_INSTALL=1 
Setting NTS_CLIENT_UPDATE=FULL 
Setting NTS_AUTO_CONFIG=true 
Setting NTS_SERVLET_ALLOW_CLIENT_INSTALL=true 
Setting NTS_64_BIT=true 
Setting NTS_NEW_INSTALL=true 
Setting NTS_INSTALLATION_TYPE=ON_PREMISE 
Setting NTS_SERVER_LANG=en 
Setting NTS_BUILD=12.0.0.0_202103161641 
Setting NTS_INSTALL_INSTANCE=1 
Setting NTS_DBCONNECTIONURL=jdbc:derby:ntsdb;create=true 
Setting NTS_AUTOSTART_HTTP=false 
Setting NTS_EXTERNAL_URL=https://travdevcen02.test.cwp.pnp-hcl.com/traveler 
Installing Traveler data files into /local/notesdata 
Traveler setup done. 
[000137:000002-00007F388F564740] Loading AutoConfiguration parameters from the environment 
[001446:000002-00007F5D1F39C740] 03/19/2021 19:56:03   Traveler: Creating database schema at version 20190922 
[001450:000002-00007FEF9671D740] 03/19/2021 19:56:04   XSP Command Manager initialized 
[001450:000002-00007FEF9671D740] 03/19/2021 19:56:04   HTTP Server: Started 
[000239:000014-00007F3178145700] 03/19/2021 19:56:08   Event: Creating the Domino Domain Monitor (11) database. 
[000239:000014-00007F3178145700] 03/19/2021 19:56:08   Created Domain Monitoring Database from template, verify ACL as changes may have been lost 
[001446:000002-00007F5D1F39C740] 03/19/2021 19:56:11   Traveler: Server started.

Example 2: Non-HA Traveler server extending existing Domino domain using JSON

In the following example, a Traveler server is added to an existing Domino domain to add mobile mail services. It is the only Traveler server, so it uses the default Derby database.

The Traveler server is configured using one-touch Domino setup with parameters in the JSON file detailed below. This file demonstrates how to set the Traveler external URL into the server document.

{
	"serverSetup": {
		"server": {
			"type": "additional",
			"name": "domTrav",
			"domainName": "existingDomain",
			"IDFilePath": "/local/notesdata/server.id",
			"additionalServerTasks": "TRAVELER"
		},
		"network": {
			"hostName": " domtrav.example.com"
		},
		"org": {
			"orgName": "existingDomain"
		},
		"admin": {
			"CN": "admin"
		},
		"existingServer": {
			"CN": "existingServer"
		}
	},
	"appConfiguration": {
		"databases": [{
			"filePath": "names.nsf",
			"action": "update",
			"documents": [{
				"action": "update",
				"findDocument": {
					"Type": "Server",
					"ServerName": "CN=domTrav/O=existingDomain"
				},
				"items": {
					"tsExternalURL": "http://domtrav.example.com/traveler"
				}
			}]
		}]
	}
}

The server.id file of the new Traveler server, and the JSON file containing the configuration values, must be copied onto the Domino /local/notesdata volume before starting the server, so the container is initially run with /bin/bash as an entry point to allow the copies to be done.

The following sample docker run command creates an interactive container that deletes itself upon termination:

docker container run --rm --name sampleContainer -it -v sampleVolume:/local/notesdata --
entrypoint /bin/bash --env SetupAutoConfigure=1 --env SetupAutoConfigureParams=sample.json --
hostname domtrav.example.com -p 1352:1352 -p 443:443 -p 80:80 -p 8080:8080 
traveler-docker:V12000_20210316164

Example 3: HA Traveler Server extending existing domain using environment variables and JSON

In the following example, a Traveler server is added to an existing Domino domain to add capacity to one or more existing Traveler servers pre-configured for high availability (HA). This Traveler server connects to an existing MySQL enterprise database server.

Note: This section is similar to the previous example.

The Traveler server is configured using one-touch Domino setup with parameters in a JSON file:

{
    "serverSetup": {
        "server": {
            "type": "additional",
            "name": "domTrav",
            "domainName": "existingDomain",
            "IDFilePath": "/local/notesdata/server.id",
            "additionalServerTasks": "Traveler"
        },
        "network": {
            "hostName": "domtrav.example.com"
        },
        "org": {
            "orgName": "existingDomain"
        },
        "admin": {
            "CN": "admin"
        },
        "existingServer": {
            "CN": "domMail"
        },
        "notesINI": {
            "NTS_DBUSER": "sqladmin",
            "NTS_DBPASSWORD": "password",
            "NTS_DBCONNECTIONURL": "jdbc:mysql://MySQLServer.sample.com:3306/dockerdb?serverTimezone=EST5EDT",
            "NTS_DBPATH": "/local/notesdata/mysql-connector-java-8.0.27.jar"                
        }
     },
    
    "appConfiguration": {
        "databases": [
            {
                "filePath": "names.nsf",
                "action": "update",
                "documents": [
                    {
                        "action": "update",
                        "findDocument": {
                            "Type": "Server",
                            "ServerName": "CN=domTrav/O=existingDomain"
                        },
                        "items": {
                            "tsExternalURL": "https://domtrav.example.com/traveler"
                        }
                    }
                ]
            }
        ]
    }
    
}

However, the parameters required for connecting to the MySQL database server cannot be specified using JSON. The recommended method for configuring the database parameters is to run the travelerUtil program while the Domino server is not running. The bring-up sequence for one-touch setup with JSON provides a good opportunity to accomplish that, because in that sequence, the docker run command starts a bash shell. You can run the travelerUtil program in that bash shell before starting the Domino bringup sequence.

As in the previous example, run the docker cp command to copy the server.id file and the JSON file into the image before starting Domino. Traveler needs to connect to the enterprise database, so you must to copy the appropriate JDBC driver for the enterprise database into the volume before starting Domino.

Another way of configuring the enterprise database connection is to put NTS_DB* parameters into a system environment variables file. If using MySQL, the JDBC driver can be obtained automatically by specifying the URL of the driver to be downloaded on the NTS_DBPATH variable, instead of specifying the path to the JDBC driver. The following is an example of specifying the NTS_DB* parameters in environment variables:

NTS_DBUSER=LNTUSER 
NTS_DBPASSWORD=password 
NTS_DBCONNECTIONURL=jdbc:mysql://MySQLServer.sample.com:3306/TRAVELER 
NTS_DBPATH=https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.23.tar.gz

The following sample docker run command creates an interactive container that deletes itself upon termination:

docker container run --rm --name sampleContainer -it -v sampleVolume:/local/notesdata --env-file 
environment.txt --env SetupAutoConfigure=1 --env SetupAutoConfigureParams=sample.json –hostname 
domtrav02.example.com -p 50125:50125 -p 50126:50126  -p 1352:1352 -p 443:443 -p 80:80 -p 8080:8080 --entrypoint /bin/bash 
traveler-docker:V12000_20210316164

Once the Domino server configuration has run once, you can restart Domino in a new container using the volume that holds the configuration information without using bash or performing the server configuration. The following sample docker run command restarts Domino using a volume that has already been configured:

docker container run --rm --name sampleContainer -it -v sampleVolume:/local/notesdata –hostname 
domtrav02.example.com -p 1352:1352 -p 443:443 -p 80:80 -p 8080:8080 -p 50125:50125 -p 50126:50126 traveler-docker:V12000_20210316164

Example 4: Sample JSON for Traveler Server with Session Authentication enabled

The following example uses the one-touch configuration process to automatically create an internet site document with Single Server Session Authentication enabled. The override rules required for Traveler to properly handle session authentication should be automatically generated on startup. For more information, see HTTP authentication.

{
    "serverSetup": {
        "server": {
            "type": "first",
            "name": "domTrav",
            "domainName": "dominoDomain",
            "additionalServerTasks": "TRAVELER"
        },
        "network": {
            "hostName": "domtrav.example.com"
        },
        "org": {
            "orgName": "dominoDomain",
            "certifierPassword": "password"
        },
        "admin": {
            "lastName": "administrator",
            "password": "password",
            "IDFilePath": "/local/notesdata/admin.id"
        }
    },
    "appConfiguration": {
        "databases": [{
            "filePath": "names.nsf",
            "action": "update",
            "documents": [{
                "action": "update",
                "findDocument": {
                    "Type": "Server",
                    "ServerName": "CN=domTrav/O=dominoDomain"
                },
                "items": {
                    "tsExternalURL": "http://domtrav.example.com",
                    "LdISite": "1",
                    "FullAdmin": [
                        "administrator/dominoDomain",
                        "LocalDomainAdmins"]
                }
            },
            {
                "action": "create",
                "computeWithForm": true,
                "items": {
                    "Form": "WebSite",
                    "FullName": "CN=WebSite/O=dominoDomain",
                    "Type": "WebSite",
                    "HTTP_EnableSessionAuth" : "1",
                    "ISiteAdrs": "domtrav.example.com",
                    "ISiteName": "Web site for traveler",
                    "ISiteOrg": "dominoDomain",
                    "WSHomeURL": "/traveler",
                    "WSHostingSrvrs": "*",
                    "Owner": "administrator/dominoDomain",
                    "LocalAdmin": "administrator/dominoDomain"
                }
            }]
        }]
    }
}

Note: Podman can be used as a replacement for docker. For more information on podman, see their documentation.