Project Keep Documentation – Run Keep with Docker

Run Keep with Docker

This section describes how to setup Keep to run as part of a Docker image. As the image also includes a complete Domino server, it will enable you to run all the Keep APis, including the ones that require a server instance of Domino.

Please also check this page

While the installation instructions may seem a bit intimidatingly at first, if you follow them carefully they will work. And once a Docker environment has been setup, it is easy to both use and maintain.

Install and prepare Docker

Check the official documentation for installing Docker on your OS.
Run through a tutorial when you are new to Docker
Create a Domino base image using the instructions in the domino-docker GitHub repository. Keep will build on top of this image

Building the keep image

The Keep image has 3 components:

the base Domino image
the Keep binaries (jar, class, resources)
the start scripts

The Docker file for Keep looks like this:

# 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
############################################################################

FROM hclcom/domino:11.0.1FP2

# 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/*.* /opt/hcl/keep/
COPY scripts/* /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

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

ENTRYPOINT ["/domino_docker_entrypoint.sh"]

USER notes

The difference to the standard Domino image are the keep binaries and the startup script, as well as the addition of the scripts to rc_domino_config. Before creating the image, make sure to:

adjust FROM to the image name you have created
create install_dir with keep files
create scripts with the startup scripts

Scripts

post_startup_script

#!/bin/sh
# Starts the vert.x tasks that talks to Domino
export GodMode=false
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/resources:/opt/hcl/keep/classes:/opt/hcl/keep/resources:/opt/hcl/keep/libs/*
export CLASSPATH=.:$V_PATH:$CLASSPATH
export NOTES_ENV=SERVER
export LOG_DIR=$NOTESDATA/logs
[ -d $LOG_DIR ] || mkdir -p $LOG_DIR
# This is important - must be writable -otherwise the docker blows 
cd $NOTESDATA
$JAVA_HOME/bin/java -XX:+HeapDumpOnOutOfMemoryError -XX:+UseG1GC -XX:+UseStringDeduplicationJVM -cp $CLASSPATH -jar projectkeep.jar > $LOG_DIR/vertx.log 2>&1 &

When you installed the expanded version of Keep (not the fat JAR) the launch line needs to look like this:

$JAVA_HOME/bin/java -XX:+HeapDumpOnOutOfMemoryError -XX:+UseG1GC -XX:+UseStringDeduplicationJVM -cp $CLASSPATH com.hcl.domino.keep.Launch > $LOG_DIR/vertx.log 2>&1 &

pre_shutdown_script

#!/bin/bash
# Before she shutdown domino we shutdown KEEP
export ADMINPORT=8889
curl --max-time 10 -d '{"shutdownkey" : "The End is near!!"}' -H "Content-Type: application/json" -X POST http://localhost:$ADMINPORT/shutdown

post_shutdown_script

#!/bin/bash
# After shutdown - kill the Java task if it is still there
pkill -9 -f projectkeep

Debugging with Docker

There is also more Docker documentation available here: Docker Documentation. Some of the information is a bit dated, in particular don’t worry about building your own Docker images as that now happens automatically. Instead focus on the section for setting up a Docker debugging environment.

Creating Docker Users and Test Data

Once you have your Docker image up and running, you’ll need to create test users and test data for the Keep Apis to run against. You’ll find instructions here: Docker Test Data

Docker install - HCL Internal

Step by step instructions for setting up a Docker development environment: Docker Install.