Checkmk as a Docker container

1. Checkmk as a Docker container

In our installation guide for Checkmk in Docker we've already shown you, how you can start Checkmk as a Docker container. We will show you extended details in this article on how to use Checkmk as a container.

2. Optional parameters during the start up

All of the following parameters are specified additionally when setting up a Checkmk site as a container and are therefore not available separately.

2.1. Using HTTPS

If Checkmk is the only web server on your dockernode, you can also bind the port to the standard (80) HTTP port. As soon as you you have multiple web servers on a dockernode however, you will probably use a reverse-proxy like NGINX – this directs the inquiries to the correct container. With this technology you can also use (possibly preexisting) HTTPS. The reverse proxy will then be addressed via HTTPS, while communicating with the container continues via HTTP.

2.2. Setting an initial password

In Checkmk, when setting up an instance a [introduction_packages#login|random password] for the default user cmkadmin is created. When creating a Checkmk container you can also assign a manual password. Just add the -e CMK_PASSWORD ='mypassword' option to the creation.

2.3. Setting your own instance ID

With the default command to create a Checkmk container the ID of the created instance will be in the cmk container. This is important to be able to access the instance via HTTP/HTTPS) and must therefore be explicit. If you have multiple containers of Checkmk on the same dockernode, you will have to manually set the ID to to ensure this uniqueness. You can do that by including the -e CMK_SITE_ID = mysite option.

2.4. Sending notifications

An important feature of Checkmk is the sending of notifications per email. Checkmk uses Postfix as MTA (Mail Transfer Agent) for outgoing mails. This postfix instance is configured to not deliver mails directly to the recipient but generally tries to fordward to a additionally mail server (SMTP relay server), which you need to provide outside of the container. Such a relay server is available in almost every organization.

You need to specify the relay mail server, who is responsible for the forwarding of the messages. Use in the option -e the variable MAIL_RELAY_HOST, e.g. -e MAIL_RELAY_HOST='' . If the mail server expects a specific host name, add the following option: --hostname ''.

Checkmk container do not support credentials for a smart host. You need to bind a postfix configuration or configuration folder from the docker node if you need them.

If you use the  Checkmk Enterprise Edition, you are able to bypass postfix at all by letting Checkmk forward directly to a smarthost. This is done by the synchronous SMTP, which is described in detail in the article about notifications. Here it is possible to use through SMTP.

2.5. Access to Livestatus via TCP

As soon as like to connect multiple Checkmk containers/instances together in a distributed environment you will need a special TCP port for the Livestatus interface. This interface allows communication between the entities. Bind this port – likewise the port for HTTP – to one of the Docker nodes and enable this TCP port in the Livestatus instance: -e CMK_LIVESTATUS_TCP = on-p 6557:6557.

2.6. Access via the command line

In some cases you will want to execute commands on the command line. Because commands for an instance are always executed via a special user, you must specify this when logging in. In Checkmk the user always has the same name as the instance he manages. With the -u cmk option, specify the user cmk:

root@linux# docker container exec -it -u cmk monitoring bash

You can then pass your commands to the instance.

2.7. Using the Event Console

Checkmk is able to receive SNMP traps and syslog messages. To be able to use this feature in a Checkmk container, the standardized ports must be provided to the Checkmk container with the following options: -p 162:162/udp -p 514:514/udp -p 514:514/tcp . In order that the instance itself also respects these ports, next activate the the appropriate add-ons in the instance with omd config. You can find these in the Addons submenu:

root@linux# docker container exec -it -u cmk monitoring bash
OMD[mysite]:~$ omd config

3. Updating a Checkmk container

Updating a Checkmk instance is not trivial if it is running in a container. This is mainly due to the architecture of Checkmk, since the configuration of an instance and other data also need to be updated in the course of a version change. An update is therefore carried out – unlike normally – with the following steps:

3.1. Backing up the Checkmk container

If you have created the container as recommended all data will be stored in a persistent file system which is independent of the container itself. It is therefore not sufficient to take a snapshot of the container to save the data. Therefore stop the container and backup the container's data to a suitable external location:

root@linux# docker stop monitoring
root@linux# docker cp monitoring:/omd/sites - > /my/path/to/backup.tar

3.2. Updating a Checkmk container

Now create a second container with the new version, so that for the update both the old version and the desired one are available. A command is given to prevent them from both from starting. Keep this shell open to so that the update can be carried out later:

root@linux# sudo docker container run -it --rm --volumes-from monitoring --name monitoring_update checkmk/check-mk-enterprise:1.5.0p6 bash

Checkmk always sets a standard for which Checkmk version should be used. Change this entry on the second container with the following command:

root@linux# docker cp -L monitoring:/omd/versions/default - | docker cp - monitoring_update:/omd/versions/

Now you can perform the update on the second container. If applicable, close the open shell after the update is complete:

root@linux# docker exec -it -u cmk monitoring_update omd update
2018-10-12 14:32:29 - Updating site 'mytest' from version 1.5.0p4.cee to 1.5.0p5.cee...

 * Updated        etc/apache/conf.d/omd.conf
Finished update.

Switching the Checkmk container over

After you have updated the (configuration) data, you can replace the old container with the new one. First rename the old container:

root@linux# docker rename monitoring monitoring_old

You can now start a container with the new Checkmk version and assign the updated file system from the old container to it:

root@linux# docker container run -dit -p 8080:5000 --tmpfs/omd/sites/cmk/tmp --volumes-from monitoring_old --name monitoring checkmk/check-mk-enterprise:1.5.0p6

You can also check in the logs to see whether the container has started without problems:

root@linux# docker container logs monitoring
Preparing tmp directory /omd/sites/cmk/tmp...OK
Starting mkeventd...OK
Starting liveproxyd...OK
Starting mknotifyd...OK
Starting rrdcached...OK
Starting cmc...OK
Starting apache...OK
Initializing Crontab...OK

Finally, delete the old container:

root@linux# docker rm monitoring_old

4. Creating your own container-images

With the help of our our repository you can also create your own  Checkmk Enterprise Edition images. Clone the current Checkmk-Git, and navigate to the docker directory. With the help of your customer data you can now create your own image:

myuser@myhost:~/git/check_mk/docker# docker build \
    --build-arg CMK_VERSION=1.5.0p5 \
    --build-arg CMK_EDITION=enterprise \
    --build-arg CMK_DL_CREDENTIALS='myusername:mypassword' \
    -t mycompany/check-mk-enterprise:1.5.0p5

During the build process you will need two external files, which will be downloaded through your customer login data. To prevent this you can also first load the necessary files manually and place them in the docker directory:

  • The Checkmk installation package for Debian Stretch
  • The public GPG-Key for the installation packet