Installing Docker Images

Operating System CLI

You need to understand the differences of specific operating system CLIs. This will affect installation of any software or running any script via a CLI. Within this document Mac variants are referenced.

MacOS

MacOS is stricter on syntax. Running a file in a folder requires ./MY_FILE. Navigating folders also requires cd .. and file and folder names are case-sensitive.

Windows

Windows is more tolerant of syntax. Just using the filename is typically sufficient for running a file. Navigating folders can be done with cd.. or cd ... And file and folder names are not case-sensitive.

Docker

You will need to run Docker commands for this and be familiar with the structures.

Dockerfile

A dockerfile defines a base image using FROM. This must be a Docker image that either you have locally or is on a Docker Registry remotely that you have configured. The only Docker Registry you will have configured is Docker Hub. No HCL images are there.

The rest of the dockerfile consists of Linux commands the Docker kernel will use to copy files and set permissions.

When the image is built from the dockerfile, all files and folders adjacent to the dockerfile are copied into a temporary holding place for the Docker kernel to run them. This means the dockerfile cannot reference anything above the folder containing the dockerfile. Any files you want to reference must be adjacent to - or in folders adjacent to - the dockerfile.

Building a Docker Image

It’s important to understand what happens when you create a Docker image. Creating the Docker image is done by issuing a docker build... command - either directly from the command line or within a bash script.

This: - looks for the image referenced in the FROM statement and creates a container from it.
- builds a temporary container for each line in the dockerfile, running the command on that line. Line 1 is run in a container based on the FROM image, line 2 is run in a container based on the result of line 1, line 3 is run in a container based on the result of line 2 etc.
- takes an image from the container for that line, and deletes the container.

The build command uses the following: - docker build - create an image.
- --tag XX - tag the resulting image with this name.
- . - use the dockerfile called “dockerfile” in this folder.

Always add a tag. This helps identify temporary images and containers that need cleaning up.

If a Docker build fails, you will have an orphaned container and images that need cleaning up: - docker ps -a lists all containers, which allows you to clean up.
- docker rm NAME will remove a containers.
- docker images lists all images. If you always use a tag, images without a tag are the ones to remove.
- docker rmi NAME will remove an image.

Architecture

Domino 11.0.1 image
-> Keep Docker Image
-> Keep Docker Debug Image

Domino Base

  1. Download Thomas Hampel and Daniel Nashed Domino Docker repository.
  2. Copy the Linux domino install file for Domino 11.0.1 from Teams, HCL Labs > General > Files > Domino Installers > 1101 GA. Paste it into the software folder and rename it “Domino_11.0_Linux_English.tar”. This is the expected filename.
  3. From a bash script run the command ./build domino.

The result should be several images, for centos, nginx and hclcom/domino. There will be one for the version and one tagged “latest”. You can view them with docker images.

Domino Data

We want our Domino data to be persisted. For that we need to create a docker volume using docker volume create --name MY_NAME. Domino will populate that on creation of the container. The data directory is the “soul” of the Domino server. So if we point another new container to that populated volume, it will run as the same server. However, we can’t have more than one Docker container using the volume at the same time.

Start Script

Keep is started using a start script. Again, this is Linux bash commands and developers should become familiar with the commands. The script is src/main/docker/install\_dir/post\_startup\_script, with a corresponding version in the docker_debuggable directory.

The following commands are used: - export to set various environment variables. Some of these - most notably the shutdownkey are used to configure Keep. You should make a note of the shutdownkey in particular, because you will need it to stop Keep from Postman, particularly for debugging Keep.
- -d and mkdir to check a directory exists, or create it.
- -f to check if a file exists.
- ....java -jar to run a Java program, in this case Keep.

Keep for Consumption

Docker Debug image

Image

  1. Download the Keep git repository, ensuring all required dependencies.
  2. Run mvn install and mvn package. If preferred, use mvn package -DskipTests=true to skip tests. This will build the projectkeep.jar in target folder.
  3. In CLI navigate to keep-core/src/main/docker in Keep repository.
  4. Run the command ./createimage.sh to run the createimage file.

The result should be an image with the name hclcom/projectkeep. It will also copy your compiled “projectkeep.jar” into the container. From now on, your Docker container will be using this version of Keep.

Container

Build and run a container from the image using the following command:

docker run -it -e "ServerName=localDev1" -e "OrganizationName=HCLLabs" -e "AdminFirstName=Domino" -e "AdminLastName=Admin" -e "AdminPassword=passw0rd" -p 1352:1352 -p 80:80 -p 8280:8880 -p 8289:8889 -v domino-data:/local/notesdata --name keep_consumable --stop-timeout=60 hclcom/projectkeep:0.8.3

The specifics here are: - docker run creates a container
- -it starts it in interactive mode, i.e. you’re seeing the Docker system console. Note: this won’t show you the Domino server console or the Keep console. There is no facility to redirect those to the system console.
- -e ... sets environment variables used for automated silent configuration of the Domino server. Change as required, but these are the minimum options. These must come first after it.
- -p 1352:1352 ... defines what ports to open on the Docker container. Ports must be exposed in the dockerfile and opened when the container is created. The first number is the port to use on your host laptop, the second is the port within the container that was exposed in the dockerfile. You cannot open additional ports or change port mappings after the container is created. The port definitions are listed in the dockerfile.
- -v domino-data:/local/notesdata means everything in the Domino data directory gets stored in the volume. The container is nothing more than a runtime.
- --name keep_consumable gives the container a specific name, “keep_consumable”.
- --stop-timeout=60 waits 60 seconds before forced shutdown. Domino anbd Keep need time to shut down cleanly.
- hclcom/projectkeep:0.8.3 is the image name (to the left of the colon) and tag (to the right of the colon). Tag will change, verify the relevant version using docker images.

Accessing

Domino and Keep will automatically start. Always retain a working container, to cross-reference if anything doesn’t work. The post\_startup\_script in “install_dir” folder identifies the location of the Domino JVM, the Domino data directory and the location of Keep logs.

Keep for Debugging

Docker Debug image

Image

  1. Download the Keep git repository, ensuring all required dependencies.
  2. Run mvn install and mvn package. If preferred, use mvn package -DskipTests=true to skip tests. This will build the projectkeep.jar in target folder.
  3. In CLI navigate to keep-core/src/main/docker_debuggable in Keep repository.
  4. Run the command ./createimage.sh to run the createimage file.

The result should be an image with the name hclcom/projectkeep.

Bind Mount

For updating the version of Keep as we develop, we want to map the “keep-core/target” directory in the repository to “/opt/hcl/keep”. Bind mounting differs significantly on Mac and Windows and is far from straightforward. Docker needs access to the relevant folder, which the operating system may block.

On Mac, as long as your repository is a subdirectory of “/Users”, you should not need to make any changes. Otherwise, you will need to go to Docker > Preferences and in Resources > File Sharing add the relevant directory. On Mac, I’ve had difficulty getting ${pwd} syntax to work - it seems to reference the container. Using a literal path works.

On Windows, you will need to go to Docker > Settings and under “Shared Drives” add the relevant local drive.

Once the container is built, you can check its settings using docker inspect CONTAINER_NAME. What you should expect to see, somewhere in the configuration, is something like this:

        "Mounts": [
            {
                "Type": "volume",
                "Name": "domino-data",
                "Source": "/var/lib/docker/volumes/domino-data/_data",
                "Destination": "/local/notesdata",
                "Driver": "local",
                "Mode": "z",
                "RW": true,
                "Propagation": ""
            },
            {
                "Type": "bind",
                "Source": "/Users/paulwithers/GitRepositories/hcl/keep/keep-core/target",
                "Destination": "/opt/hcl/keep",
                "Mode": "",
                "RW": true,
                "Propagation": "rprivate"
            }
        ],

The key parts are:
- the “type”, bind rather than volume, identifying it’s mapped to a local directory.
- the “source”, which must be the target directory of keep-core in the repository.
- the “destination”, which must be “/opt/hcl/keep”, the directory from the start script picks up the projectkeep.jar to run. If it is not, the container will use the version it was built with, in its own “/opt/hcl/keep” directory.

Container

Build and run a container from the image using the following command:

docker run -it -e "ServerName=localDev1" -e "OrganizationName=HCLLabs" -e "AdminFirstName=Domino" -e "AdminLastName=Admin" -e "AdminPassword=passw0rd" -p 1352:1352 -p 80:80 -p 8280:8880 -p 8289:8889 -p 8000:8000 -v domino-data:/local/notesdata -v /Users/paulwithers/GitRepositories/hcl/keep/keep-core/target:/opt/hcl/keep --stop-timeout=60 --name keep_debuggable hclcom/projectkeep:debug

Note, we add a second -v mapping, to the bind mount in the Git Repository. This allows us to just run mvn package, restart the container, and see the updated changes.

Note, we also open port 8000 for the remote debugger.

Debugging

By default Domino will always start without listening for the debugger. In order to start keep listening for a debugger, you need to shutdown Keep with an additional variable in the payload:

"debug": true

This will tell Keep to create a file called debug.on in $NOTESDATA/keepconfig.d directory. Shutting down Keep without this parameter will remove the file from $NOTESDATA/keepconfig.d.

You can verify this by running docker exec -it keep_debuggable /bin/bash in a Terminal prompt (the Docker container needs to be running to do this). Then switch to the keepconfig.d directory (cd /local/notesdata/keepconfig.d) and list the files (ls).

If the file exists, when you restart the container Domino will automatically start, but Keep will wait for a debugger to connect. In order to interact with Keep via breakpoints, Keep needs to suspend and wait for the debugger to connect. You cannot interact with Keep in this container until a debugger is connected. This can be done from Eclipse.

Debug Configuration

  1. Select Run > Debug Configurations.
  2. Create a new Remote Java Application debug configuration.
  3. Browse to the Keep source code as the project.
  4. Ensure host and port are “localhost” and port 8000 (or the port you assigned in the docker run command.
  5. On the Source tab, add as a Java Project the Keep source code in Eclipse.

Whenever the Docker container starts, start the debugger in order for Keep to load. You can disconnect the debugger and reconnect at leisure, but the debugger must be connected once for Keep to complete loading.

You can prevent Keep from starting in debug mode by issuing the shutdown command from Postman either without the debug property in the body, or by setting "debug": false. You can verify this has worked by checking that there is no debug.on file in the keepconfig.d directory. Alternatively, use a container built from the non-debuggable Docker image.

Testing Changes

If you make changes: - Compile.
- Stop the Docker container.
- Run mvn package, which will regenerate the projectkeep.jar in the keep-core/target directory.
- Start the Docker container.
- Connect the debugger in Eclipse.
- Test.