Domino Docker and Debugging

Given that Domino once was build to run on 486 capacity of servers, Docker and Domino are posed to be a match made in heaven (eventually). Jesse shared shared his Weekend Domino-Apps-in-Docker Experimentation, Paul shared his learning points and Daniel provided the invaluable Domino on Docker build scripts. So it's time to contribute my share. The topic is slightly more exotic

Debug a Java application running on Domino in a Docker container

Before we can get cooking, we need to know what ingredients we need:

The Domino on Docker build scripts including the required Domino Linux installer
Some general understanding how Daniel's Domino Startup Script works
Docker desktop installed on our machine (I use macOS, but I know someone, who can share his Windows experience)
Basic understanding of Docker
A Java project that shall be debugged. I use Apache Maven, as discussed before, but Gradle will do just fine
Understanding how to debug Java

Our objective: Create a Domino image that loads the Java application from its host file system, so we do not need to rebuild the container on Java changed. An instance of this image shall allow to connect a debugger to that Java application

Foundation: the Domino image

First we have to build a Domino Docker image, configure a server using a docker volume. This has been mapped out in the domino-docker project and its slighly hidden documentation. Just a quick recap:

Build the image using ./build domino
Create a volume using docker volume create keep_data
Run the instance once to setup the domino

docker run -it -e "ServerName=Server1" \
    -e "OrganizationName=MyOrg" \
    -e "AdminFirstName=Doctor" \
    -e "AdminLastName=Notes" \
    -e "AdminPassword=passw0rd" \
    -h myserver.domino.local \
    -p 80:80 \
    -p 1352:1352 \
    -v keep_data:/local/notesdata \
    --stop-timeout=60 \
    --name server1 \
    hclcom/domino:11.0.1

We shut down the instance once you have confirmed it works. We don't need it thereafter, we only need the volume and image. Of course there's no harm keeping it around

The application image

Docker is like Ogres, so for our application we build another layer. Big advantage of this approach: when a newer Domino image becomes available (I heared 12.0 will be awesome), we only need to change one line in our own dockerfile and nothing in the Domino image

############################################################################
# Copyright Nash!Com, Daniel Nashed 2019, 2020 - APACHE 2.0 see LICENSE
# Copyright IBM Corporation 2015, 2019 - APACHE 2.0 see LICENSE
# Copyright HCL Corporation 2020 - APACHE 2.0 see LICSENSE
############################################################################

# DEBUG VERSION - DON'T DEPLOY INTO PRODUCTION!!!!

FROM hclcom/domino:11.0.1

# Headers
LABEL DominoDocker.maintainer="stephan.wissel@hcl.com"

USER root

# Prepare environment for KEEP

RUN mkdir -p /opt/hcl/keep
RUN mkdir -p /opt/hcl/domino/scripts

COPY install_dir/*_script /opt/hcl/domino/scripts/

RUN chown -R notes:notes /opt/hcl/keep
RUN chown -R notes:notes /opt/hcl/domino/scripts
RUN chmod +x /opt/hcl/domino/scripts/*script

RUN echo 'DOMINO_PRE_SHUTDOWN_SCRIPT=/opt/hcl/domino/scripts/pre_shutdown_script' >> /etc/sysconfig/rc_domino_config
RUN echo 'DOMINO_POST_STARTUP_SCRIPT=/opt/hcl/domino/scripts/post_startup_script' >> /etc/sysconfig/rc_domino_config
RUN echo 'DOMINO_POST_SHUTDOWN_SCRIPT=/opt/hcl/domino/scripts/post_shutdown_script' >> /etc/sysconfig/rc_domino_config

# Expose Ports NRPC HTTP LDAP KEEP KEEPADMIN KEEPMETRICS DEBUGGING
EXPOSE 1352 80 389 8880 8889 8890 8000

ENTRYPOINT ["/domino_docker_entrypoint.sh"]

USER notes

Let us break down what that docker file does:

It is based on the Domino image hclcom/domino:11.0.1 we built in the previous step
It creates directories under /opt/hcl where you also can find the Domino binaries
It copies and makes executable scripts and Jar files
It ammends the rc_domino_config file to point to the scripts we just copied
It exposed a few more ports: 8880, 8889, 8890 are application specific, 8000 is our debug port

The scripts

The most interesting one is the post_startup_script than runs once Domino is up and running. It will run the Java application, waiting for the debugger to be ready:

#!/bin/sh
# Starts the vert.x tasks that talks to Domino
export DEBUG=true
export DOMINO_HOME=/opt/hcl/domino/notes/latest/linux
export JAVA_HOME=/opt/hcl/domino/notes/latest/linux/jvm
export NOTESDATA=/local/notesdata
export DYLD_LIBRARY_PATH=$DOMINO_HOME
export LD_LIBRARY_PATH=$DOMINO_HOME
export V_PATH=/opt/hcl/keep/fancyapp.jar
export CLASSPATH=.:$V_PATH:$DOMINO_HOME/jvm/lib/ext/Notes.jar:$CLASSPATH
export NOTES_ENV=SERVER
export LOG_DIR=$NOTESDATA/logs
[ -d $LOG_DIR ] || mkdir -p $LOG_DIR
# This cd is important - must be writable -otherwise the docker blows
cd $NOTESDATA
echo "Java will start in debug mode"
$JAVA_HOME/bin/java -jar -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y $V_PATH > $LOG_DIR/vertx.log 2>&1 &

Let us break this down:

The export statements establish where to find what
The Java app is run from the Domino data directory
The -agentlib:jdwp=transport=dt_socket tells the JVM to open a debug session via a socket connection
The address=8000,suspend=y declares the port and that the application shall wait until the debugger has attached
Finally 2>&1 & tells us: StdOut and StdErr go to the same place and the app will run in the background

Eclipse debugger

In Eclipse we create a new "Run Configuration" as "Remote Java Application" with a Standard (Socket Attach) connection type and host/port localhost/8000. You can't deploy this to a K8S environment since we will load the Jar from our local disk. Of course you can modify the setup to load the Jars for a different location

Remote Eclipse Debugger

Building and starting the new image

Build the image based on the docker file: docker build --tag hclcom/keep:debug

We are reusing the volume created for a vanilla Domino server, so all the configuration is completed, IDs and names.nsf exist. We now create a new instance based on the new image

#!/bin/bash
# Start my local domino server for debug
docker run -it \
 -h myserver.domino.local \
 -p 81:80 \
 -p 1352:1352 \
 -p 8880:8880 \
 -p 8889:8889 \
 -p 8890:8890 \
 -p 8000:8000 \
 -v keep_data:/local/notesdata \
 -v /[Path to your Java Project]/target:/opt/hcl/keep \
 --stop-timeout=60 \
 --name Server1Debug \
 hclcom/keep:debug

Lots of steps. However once setup, you can simply restart the instance using Docker desktop whenever your Java has changed. There are a few Gremlins building the whole thing on Windows, running seems to be fine. This might be the time to give WSL another look.

As usual YMMV. Next stop: more automation building production ready images

Posted by Stephan H Wissel on 30 June 2020 | Comments (1) | categories: Container Docker Domino HCL Notes K8S Maven