Building custom add-ons for your Domino container image

This is a post that I thought I had already written, but I realised today that I hadn’t. It’s about a feature that Daniel Nashed added to the Domino container community project in the past year and that I showed in my presentations on the Domino container project at Engage and OpenNTF. But apparently, apart from that, Daniel and I never documented it. So here it is. The documentation on how to create your own custom add-on packages for your Domino container image.

Why custom add-ons for Domino containers?

When you use Domino containers, the Domino program directory (everything under /opt) is not persistent. This means that any change you make to files in that directory are lost whenever you restart the Domino container. And there are many reasons why you might want to make changes to files or add files to the Domino program files. For example:

  • You want to add a certificate to your cacerts (/opt/hcl/domino/notes/latest/linux/jvm/lib/security/cacerts) for your Java agents to connect to other systems
  • You want to make changes to the java security policy (/opt/hcl/domino/notes/latest/linux/jvm/conf/security/java.security)
  • You want to add an extra Domino task (/opt/hcl/domino/notes/latest/linux/<domino program task>)
  • Many third party addons also write files to the Domino program directory.

You might also want to add extra libraries or scripts to the Linux os inside the container. For example, certain python libraries which you want to use in a python script that you use from an agent in your Domino application.

To make these changes/additions persistent, these changes/additions need to be done to the Domino container image. If you have to do this with the standard docker/podman tooling, this requires quite a bit of knowledge, but luckily in the Domino container community project, this was made easy by the custom-addon functionality.

Preparing a custom add-on package

The build.sh command from has the option to add custom add-ons by using the the option “-custom-addon=” or as the help command of the build-script describes it:

-custom-addon=x  specify a tar file with additional Domino add-on sofware to install format: (https://)file.taz#sha256checksum

This option is multi-value. You can add multiple add-ons by separating the values with a comma (,). So every add-on can be in its own tarball. The sha256checksum is a security feature. If you’ve added a custom-addon to your build configuration which you reuse to update the base image libraries, in theory, someone could add malicious software to the tarball, which you unknowingly would import in your image the next time you rebuild it. The sha256 checksum prevents this, as the checksum would change if the tarball has changed. As a result, the add-on would not be added to your Domino image.

You can either place the tarball on a webserver that is reachable from your machine where you build your Domino image, or put it in the same location where all install packages were downloaded (default: /local/software). If you specify a url, the build-script will try to download the package from a webserver, if you only specify a filename, the build-script assumes it is in the default software location.

Structure of the tarball

There are 3 predefined directories and one predefined file for the tarball. Let me explain these from an example of a tarball’s file tree:

├── domino-bin
│   ├── jvm
│   │   ├── conf
│   │   │   └── security
│   │   │   └── java.security
│   │   └── lib
│   │   └── security
│   │   └── cacerts
│   └── libnshsmtp.so
├── domino-data
│   └── nshsmtp
│   ├── nshsmtpconfig.ntf
│   ├── nshsmtpipcache.ntf
│   ├── nshsmtpjournal.ntf
│   └── nshsmtplog.ntf
├── install.sh
└── linux-bin
└── nshmailx

domino-bin

The domino-bin directory refers to the /opt/hcl/domino/notes/latest/linux directory, so any file in here will be added to or replacing a file in this directory or one of its subdirectories. As you can see in the example above, this tarball adds the libnshsmtp.so as a Domino program task (this is the library for Spamgeek) and adds a custom java security policy and cacerts key database (just as an example. The latter two are not related to Spamgeek).

domino-data

Any file or directory with file here will end up in your /local/notesdata directory, but only when setting up a new server with this Domino image. As the notesdata directory is on a persistent volume, changes to the image won’t make any changes to an existing notesdata directory.

linux-bin

Files in this directory are added to /usr/bin. This can be handy if you want certain scripts available in the container for easier troubleshooting. The example file, is a script that you can use to send SMTP mail and which can be very useful in testing mail send problems. linux-bin is not meant for adding extra linux packages to the container that would be installed by yum/dnf/apt-get as those would be added by using the option ‘-linuxpkg=’ in the build.sh script.

install.sh

install.sh is a script that is executed during the image build process and which can be used to make changes to the image that can’t be made through the three predefined directories. It could be used, for example, to add extra python packages by pip install <package> commands. You’re basically only limited here by your own imagination.

Creating the tarball and sha256 hash

Once you have your files in the above structure, you can create your tarball:

# tar cvzf MyAddon.taz *
domino-bin/
domino-bin/jvm/
domino-bin/jvm/conf/
domino-bin/jvm/conf/security/
domino-bin/jvm/conf/security/java.security
domino-bin/jvm/lib/
domino-bin/jvm/lib/security/
domino-bin/jvm/lib/security/cacerts
domino-bin/libnshsmtp.so
domino-data/
domino-data/nshsmtp/
domino-data/nshsmtp/nshsmtpjournal.ntf
domino-data/nshsmtp/nshsmtpipcache.ntf
domino-data/nshsmtp/nshsmtpconfig.ntf
domino-data/nshsmtp/nshsmtplog.ntf
install.sh
linux-bin/
linux-bin/nshmailx

This created a file MyAddon.taz. Next you get the sha256 hash of this file:

# sha256sum MyAddon.taz
63cceac799a5db23fe06f0fbae5de0259a7ff0ec016d7be03cb940a2d6139f36 MyAddon.taz

If you move your add-on file to your software download directory (default:/local/software), you can use it in your build command by running:

./build.sh -custom-addon=MyAddon.taz#63cceac799a5db23fe06f0fbae5de0259a7ff0ec016d7be03cb940a2d6139f36 menu

This will load the usual build menu, but you will see in the menu a line: Add-Ons : MyAddon.taz.

The future of custom add-ons…

Of course, it’s hard to predict the future, but I can say what I would like the future to look like for Domino container custom add-ons. This feature provides the means to create an app store for HCL Domino containers. A site where you can pick which add-ons you would like to add to your Domino image and where you can just click a button to give you a “https://domino-addons.example.com/SupercoolAddon.taz#<hash of this file>” link, which you can add to your build command. Just imagine the possibilities! New versions of OnTime, or third party addons would simply appear on this website and you can grab them straight from here. For now it’s just a vision, but I hope to see the day!