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.
For details on a Keep docker file check here
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
- Download Thomas Hampel and Daniel Nashed Domino Docker repository.
- 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.
- 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
Image
- Download the Keep git repository, ensuring all required dependencies.
- Run
mvn install
andmvn package
. If preferred, usemvn package -DskipTests=true
to skip tests. This will build the projectkeep.jar in target folder. - In CLI navigate to keep-core/src/main/docker in Keep repository.
- 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
Image
- Download the Keep git repository, ensuring all required dependencies.
- Run
mvn install
andmvn package
. If preferred, usemvn package -DskipTests=true
to skip tests. This will build the projectkeep.jar in target folder. - In CLI navigate to keep-core/src/main/docker_debuggable in Keep repository.
- 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.
Debuggable 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.
- Select Run > Debug Configurations.
- Create a new Remote Java Application debug configuration.
- Browse to the Keep source code as the project.
- Ensure host and port are “localhost” and port 8000 (or the port you assigned in the
docker run
command. - 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.