Installing Docker Images

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.

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.

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.

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.