Domino-docker explained – Part 4 : The domino_container script

Posted on by

In the previous part, I showed how you can simply start and stop and open the Domino console with the domino_container command. This piece of script is responsible for interacting with the Domino container in a way where the average administrator doesn’t even have to realise that Domino is running inside a container. There are many more functions in this script that will help you manage your Domino server and in this part I will discuss them.

Commands

To see which commands are supported by the script, you can simply type ‘domino_container’.

(Using config file /etc/sysconfig/domino_container)

Nash!Com Container Script Version 1.0.2
(Running on Podman Version 3.3.0-dev)

Usage: domino_container

       start  | stop | restart | status | statusd | inspect | console | config | env
       domino | bash | update  | attach | remove  | cleanup | rmi     | port
       build  | load | pull    | restartpolicy    | install | version | help

The idea of the domino_container script is that you can do everything you need to do with your Domino container without ever using a docker/podman command. That way an administrator doesn’t need to know which container technology is used. I’ll walk through the commands.

start [live]

If a container already exists, it will start the container, comparable to a docker/podman start <containername> command. If no container exists, it will create the container, comparable to a docker/podman run command. I have come across situations where the start command wouldn’t work because of remaining containers, pid files etc. The solution for this is to use the cleanup command before you try start again.

The live option which you can give along with the start command, attaches to the entrypoint script. This can be useful on first start of a new container to see what is happening in the entrypoint script.

stop

This command stops the container

restart

Performs a domino_container stop command and a domino_container start command

status

This command will return the status of the Domino container as in “running”, “created”, “exited” etc.

statusd

This command returns the output of a ‘systemctl status domino.service’ command. Docker uses its own daemon to start and stop containers, so this command will provide no output if you use Docker as container engine. Podman does use systemd files, so on systems using Podman this command will show the status of the domino service.

inspect

Daniel really put some work in this command to make a very useful overview of your Domino container with both information from the container itself and information from the Domino server running inside. This is what mine looks like:

------------------------------------------------------------------------------------------
 Runtime        :  Podman 3.3.1
 Status         :  running
 Health         :  healthy
 Started        :  03.10.2021 10:33:01

 Name           :  domino
 Current Image  :  localhost/martdj/domino:latest
 New Image      :  martdj/domino:latest
 Version        :  12.0
 Domino Ver     :  12.0.0
 BuildTime      :  11.06.2021 17:08:35

 Hostname       :  domino.martdj.nl
 Volumes        :  /local/domino
 Mounts         :  /local

------------------------------------------------------------------------------------------
 Container ID   :  81f59d2d13dc
 Image-ID       :  47f325aa1985
------------------------------------------------------------------------------------------

 Image Size     :  2055 MB
 NetworkMode    :  bridge
 Driver         :  overlay
 Container Ports:
                  1352/tcp -> 192.168.7.90:1352
                  80/tcp -> 192.168.7.90:80
                  443/tcp -> 192.168.7.90:443
                  25/tcp -> 192.168.7.90:25
                  389/tcp -> 192.168.7.90:389
                  636/tcp -> 192.168.7.90:636
                  8642/tcp -> 192.168.7.90:8642
                  143/tcp -> 192.168.7.90:143
------------------------------------------------------------------------------------------

console

If you’ve ever worked with Daniel’s start/stop script for Domino servers on Linux, you’re probably aware of the rc_domino console command, which lets you interact with the console of your Domino server. This command uses this script inside the container and so gives the same result: an interactive console of your Domino server.

One big caveat: This script is not available in the docker images that are provided by HCL, so the console command won’t work if you use their Docker images. That’s really a shame as this is a very useful command and one extra reason for me to build my own images.

config / cfg

This command lets you edit your Domino container’s configuration, as stored in /etc/sysconfig/domino_container.

env

This command lets you edit the environment file that’s configured in the CONTAINER_ENV_FILE variable in the domino_container configuration file from the config command. By default, /etc/sysconfig/env_container_domino12. It contains the one-touch setup parameters to configure a new Domino server.

domino [command]

The domino command works as a proxy which forwards all commands to the start/stop script inside the container which I mentioned with the console command. As such, it’s only available if you build your own image, as opposite to using the Docker images that HCL provides. There are quite a few commands you can give along, but this is really more advanced stuff. These are a few examples of commands which I find really useful.

  • domino restart live – This will let you follow the shutting down and starting up of the Domino server, just like if you were using the Java controller and Java console. There’s also a start and stop live command.
  • domino lastlog – Shows the last 100 lines of the console log
  • domino ini – Opens the notes.ini in an editor
  • domino listini – outputs the notes.ini. Useful combined with grep to search for a specific parameter

bash [root]

Opens a new bash shell inside the container as the notes user in the /local/notesdata directory. Lets you interact with the Domino container as if it were just another Domino server on a Linux box. You can also use the optional ‘root’ parameter to start a bash shell as root. Just remember that any changes you make outside the persistent directories, will be lost when you restart the container.

update

Checks if the container is still based on the latest image as provided in the container configuration (domino_container config). It checks the image id of the image as defined in the container configuration and compares that to the image id of the image it’s currently using. If they don’t match, it will stop and remove the container and create a new one based on the new image. This also gives you the freedom to base your domino container on a different image. For example, one with HCL Volt added.

attach

This command corresponds to the standard docker/podman attach command, which attaches to the running command in the container. In case of the Domino container, that’s the entrypoint script. It could be useful to follow what’s happening on starting the container, but doesn’t have much use otherwise.

remove / rm [force]

Remove the domino container. If the container is still running this command won’t work, unless you use the ‘force’ option. It can be useful to remove the container if the container, for whatever reason, became corrupted (for example, because you edited files inside the container, which you shouldn’t have edited). If you remove the container, it will be recreated on the next start. Another case when you want to remove the container is when you created a new Domino server, but didn’t assign the correct rights to your persistent directories (the ones configured in the domino_container config). The setup will fail in this scenario, but the entrypoint script to set up the Domino server will only run once. Remove the container in this case, to force the set up script to run again, after you’ve fixed the rights on the persistent directories.

If there’s a problem with the container, due to a crash, and you use podman as container engine, it’s better to use the cleanup option.

cleanup

The difference between this option and the previous remove command is that cleanup will also remove any lingering pid files for the Domino container. These can be leftovers if the Domino container is started through systemd (default for podman). You can also opt to simply always use the cleanup command instead of remove.

removeimage / rmi

If there’s no remaining domino container, this command will remove the Domino image. The image is used to create a container, so be careful with this command, because if you use a local Domino image (which you do if you followed part 2 of this series), you can start again from scratch!

port

This command gives a list of all forwarded ports from the container. If your container uses the host network (which is the default), there is no port forwarding as the container uses the same network as the host. In that case, this command will return no ports.

build

This command is used to build images. We looked at this command in part 2 already, and it will be used further in parts 5 & 6, so you’ll find a more elaborate explanation of what you can do with this command there.

load / upload

The load/upload command is meant to load the latest official Domino docker image from HCL in the local repository. It tells you where to download this image. However, simply using

docker/podman load --input <tar archive file>

is not that hard and more flexible in my view.

pull

This is a useful function if you’ve uploaded your image to a private Docker registry. In that case, it pulls the latest image from this registry if the registry contains a newer version of the Domino image.

restartpolicy [no | on-failure | always | unless-stopped]

Update the restart policy for the container. Only relevant if you’re using Docker as container engine. You can use domino_container inspect to see the current policy.

enable / on

If you’re using podman as container engine, this command with enables the systemd service to make the container automatically start on booting the host. Analog to systemctl enable domino.service

disable / off

Does the opposite of enable / on. Analog to systemctl disable domino.service

install

This command installs podman as container engine if no container engine (podman or docker) is found.

version

Shows the version of the domino_container script.

help

A short summary of this article

Conclusion

As you can see, there are a lot of commands in the domino_container script to handle almost anything you can think of without ever having to use a docker or podman command. Many options you’ll probably hardly ever use. The ones that I use most for daily administration are: start, stop, restart, console and bash. If you just remember those five, you’re good to go.

In the next part, I’ll look at adding addons on top of the Domino container. In particular Traveler, Verse and Volt.