Run Domino REST API with a Docker image

The Domino REST API Docker image is built on top of an HCL Domino Docker image, inspired by the open source templates. All configuration options found there can be applied to the Domino REST API Docker image. You will need to decide if you want to run a standalone server or an additional server in an existing Domino domain.

Tip

The Domino REST API Docker image contains a Domino server. You don't need a separate Domino installation. The image is completely self contained. Domino REST API is a Domino service, using the network free C API. So there is no scenario where an "only Domino REST API" container would work.

Prerequisites

Running Domino REST API with a Docker image requires the following:

• Docker Desktop

  A Docker installation, both Docker (for servers) or Docker Desktop are suitable. Download and install Docker Desktop for your environment (Linux, Windows or macOS).

  Docker Desktop License

  Docker desktop recently became subject to a Docker subscription, make sure you are compliant or use the command line.

• Docker Compose

  When you install a Docker Desktop version (Windows, macOS), Docker compose is already included. For servers, it's an additional install.

• Domino REST API Docker image.

  Download the image as an archive file from HCL Software License and Download Portal  or My HCLSoftware Portal . For more information, see Download Domino REST API.

  Important

  • If using a Docker image from HCL Container Repository (Harbor) , take note of the image name of the latest Docker image version from Harbor indicated in What's New, update the CONTAINER_IMAGE variable in the .env file, and then execute docker-compose.

  • If prompted for access to HCL Container Repository (Harbor), obtain your HCL Container Repository username and password, and then sign-in using docker login hclcr.io command and the obtained credentials.

• Docker compose file

  Download the file from downloadable resources. Select the matching one for either a standalone primary or an additional server.

• .env file.

  Download the sample.env from downloadable resources. Rename the file to .env.

• A valid Domino server id, when you want to run an additional server in your existing domain.

Persistent volume

A Domino server uses one persistent volume to store its data. This volume also stores log files and the server’s ID file. When you remove the container, that volume remains and is reused when you start a new container instance.

Note

When you want to run multiple servers, create separate volumes for each. DO NOT share volumes between running instances.

Store the following files in a folder

• server id

  Make sure that your server id file is named server.id.

• docker-compose.yml.

  Rename the compose file you downloaded from resources to docker-compose.yml.

  Note

  You can configure multiple Domino servers in a single compose file. For details, check the Docker compose documentation. With Domino REST API in mind, each server needs its own volume.

• .env

  Edit the .env file from resources to update your values. For more information, see Update .env file.

Load Docker image

For docker image from HCL Software License and Download Portal or My HCLSoftware Portal

Load the docker image that you've downloaded from prerequisites. Make sure you extract the tar.gz file  first.

docker load -i [name_of_tar_file].tar

After loading the image, note the image name that was output. You need the image name to update the CONTAINER_IMAGE variable in the .env file.

Example loaded image name

• From earlier releases: docker.qs.hcllabs.net/hclcom/projectkeep-r12:1.10.0
• Starting v1.0.7 release: domino-rest-api:1.0.7

For docker image from HCL Container Repository (Harbor)

Take note of the image name of the latest docker image version for docker compose .env file from Harbor indicated in What's New. You need the image name to update the CONTAINER_IMAGE variable in the .env file.

Example image name

hclcr.io/domino/restapi:1.0.6

Update .env file

Depending on the compose file you choose, a different set of variables needs to be replaced. If a variable isn't in the compose file, you don't need it. We keep the variable names in sync with One-touch Domino setup, thus in the compose file you will find gems like SERVERSETUP_SERVER_NAME: "${SERVERSETUP_SERVER_NAME}". This makes naming of variables consistent.

Tip

Refer also to the official List of One-touch environment variables for reference.

To update the variables in the compose file, update the variables in the .env file with your values. Replace all values after the equal = sign. Refer to the table below for guidance on the variables, their example values, and additional information.

Variable	Example	Remarks
CONTAINER_HOSTNAME	domino.acme.com	Pro tip: use something.local for local testing
CONTAINER_IMAGE	docker.qs.hcllabs.net/hclcom/projectkeep-r12:1.10.0 (example name for docker image from HCL Software License and Download Portal or My HCLSoftware Portal from earlier release) domino-rest-api:1.0.7 (example name for docker image from HCL Software License and Download Portal or My HCLSoftware Portal starting v1.0.7 release) hclcr.io/domino/restapi:1.0.6 (example name for docker image from Harbor)	For docker image downloaded from HCL Software License and Download Portal or My HCLSoftware Portal, update based on the name of the loaded image, such as the example shown above, or use docker images ls to see the exact image name. For docker image downloaded from Harbor, update based on the image name of the latest docker image version for docker compose .env file from Harbor indicated in What's New.
CONTAINER_NAME	domino-keep-test02
CONTAINER_VOLUMES	domino_keep_notesdata	no spaces or special characters
SERVERSETUP_ADMIN_CN	Peter Parker
SERVERSETUP_ADMIN_FIRSTNAME	Paul
SERVERSETUP_ADMIN_LASTNAME	Herbert
SERVERSETUP_ADMIN_PASSWORD	domin4ever
SERVERSETUP_EXISTINGSERVER_CN	domino01	YOUR EXISTING SERVER
SERVERSETUP_EXISTINGSERVER_HOSTNAMEORIP	10.45.10.3	MUST BE REACHABLE, can use DNS too
SERVERSETUP_NETWORK_HOSTNAME	keep01.domino.acme.com	MUST RESOLVE
SERVERSETUP_ORG_CERTIFIERPASSWORD	supersecret
SERVERSETUP_ORG_ORGNAME	Stark Industries	YOUR EXISTING ORG
SERVERSETUP_SERVER_DOMAINNAME	MarvelPhase4	YOUR EXISTING NOTES DOMAIN
SERVERSETUP_SERVER_NAME	keep-server-01
SERVERSETUP_SERVER_SERVERTASKS	replica, router, update, amgr, adminp, http, keep	Refer to the Domino REST API task page.

Run Domino REST API

Start Domino REST API using docker-compose on all supported platforms by running the following command:

docker-compose up

Note

• Start in the directory where the files server.id and docker-compose.yml are located.

• The setup can take a few minutes, depending on your hardware and the network speed to your primary server.

• If prompted for access credentials to HCL Container Repository (Harbor), see Obtain authentication token from HCL Container Repository.

Tip

When you don't have DNS setup, amend your hosts file for name resolution:

• /etc/hosts on Linux or macOS
• C:\Windows\System32\drivers\etc\hosts on Windows

• You can then use Docker desktop to start/stop the container.
• Use docker-compose up -d to run docker in the background.
• Don't run two Domino REST API containers sharing the same volume at the same time, alternate (such as debug/non-debug) or with 2 different volumes is OK.

Validation

To validate that an instance is successfully running on a container:

• A Docker container should be created and running on your Docker machine. To check that the container is up, run the following command on a terminal:

docker ps

• The container should be accessible via

docker exec -it $containername /bin/bash

• Domino should be accessible on http://$host:80 (might need configuration).
• Domino REST API should be accessible on http://$host:8880.
• Domino REST API Management should be accessible on http://$host:8889.
• Metrics should be accessible on http://$host:8890/metrics.

Alternate Docker configuration

When you run your Domino servers on Linux, you probably use the Nashcom startup script for Domino. On this foundation, the GitHub.com hosted Domino Docker project offers management scripts that allows easy management of your Docker container using a command domino_container.

Installation steps are as follows:

1. Clone the domino-docker repository: git clone https://github.com/HCL-TECH-SOFTWARE/domino-container

2. Change into the installation directory: cd start_script

3. Run the installer: ./install_domino_container

   Note

   You might need sudo to run the installer.

Now you have the command domino_container at your disposal:

• Use domino_container cfg to set your configuration.
• Use domino_container env for the environment values.
• Start Domino and Domino REST API using domino_container start.
• Learn more about the scripts using domino_container help.