Checkmk
to checkmk.com

1. The basics

There are numerous reasons why many users would want to operate software in a Docker container. Checkmk can also be used in a Docker environment. One application case may be to monitor a dynamically-created container group and to make Checkmk a part of this group. Should the container group no longer be needed the Checkmk instance can also be removed.

Important: Even it is possible and very easy to integrate Checkmk into a containerized infrastructure, it is not always the best solution. Since you get a reduced performance with every virtualisation and your monitoring in general should have a minimum of physical dependencies, it is not a good solution to use a Checkmk container to monitor your complete infrastructure. But it may be a good one, to integrate a Checkmk container in a self-contained container cluster, because in this case you would be able to monitor this cluster from the inside. So verify especially in this case if the tool Docker/Container is the best to fit your actual requirements.

In order to make the setting-up as easy as possible for you, we supply each Checkmk edition inclusive of its own specific image, which contain the Linux operating system Debian in addition to Checkmk:

CRE Checkmk Raw Edition

Docker Hub

CEE Checkmk Enterprise Editions

Checkmk download page (for the Free Edition), Checkmk customer portal

Note: Deployment in Docker Hub allows you to download and install in one command, as we will show in the chapter on installing the Raw Edition.

In this article we will guide you through the installation of Checkmk in Docker, and show a few tricks that will make life with Checkmk in Docker easier. Further information can be found in the article Checkmk server in a Docker container.

2. Prerequisites

To execute the commands presented in this article, you need a working installation of the Docker Engine and basic knowledge of its use.

3. Installation of the Raw Edition

CRE Getting started with the CRE Checkmk Raw Edition in Docker is easy. You can get a suitable image directly from the Docker Hub. This is done with just a single command on the command line. With this command not only will a Docker container with Checkmk be created, but also a monitoring site named cmk is set up and started. This site will be immediately available for a login as the cmkadmin user.

root@linux$ docker container run -dit -p 8080:5000 --tmpfs /opt/omd/sites/cmk/tmp:uid=1000,gid=1000 -v monitoring:/omd/sites --name monitoring -v /etc/localtime:/etc/localtime:ro --restart always checkmk/check-mk-raw:2.0.0-latest
Unable to find image 'checkmk/check-mk-raw:2.0.0-latest' locally
2.0.0-latest: Pulling from checkmk/check-mk-raw
69692152171a: Pull complete
9c7de4c0761f: Pull complete
6707e96b1346: Pull complete
b6a32bb602b9: Pull complete
906e243cffff: Pull complete
dcc72c1a4553: Pull complete
Digest: sha256:a4f25bd3b81eb7d3e1f4caa11025243b9fc4c8397ffdf41ffb23ca685161bfcd
Status: Downloaded newer image for checkmk/check-mk-raw:2.0.0-latest
73a86e310b60bfdd9ebe76ad110139b612bce02b22dd6aaf5fdb341323397299

Some more information on the available options:

OptionDescription

-p 8080:5000

By default the container’s web server listens on port 5000. In this example port 8080 of the Docker node will be bound to the port of the container so that it is accessible from outside. If you do not have another container or process using the standard HTTP port 80, you can also tie the container to it. In such a case the option will look like this: -p 80:5000. The use of HTTPS will be explained in the article Checkmk server in a Docker container.

--tmpfs /opt/omd/sites/cmk/tmp:uid=1000,gid=1000

For optimal performance, you can use a temporary file system directly in the RAM of the Docker node. The path of this file system is specified with this option. If you change the site ID this path must also be adjusted accordingly.

-v monitoring:/omd/sites

This option binds the data from the site in this container to a persistent location in the Docker node’s file system. The data is not lost if the container is deleted. The code before the colon determines the name — in this way you can clearly identify the storage location later, for example, with the docker volume ls command.

--name monitoring

This defines the name of the container. This name must be unique and may not be used again on the Docker node.

-v /etc/localtime:/etc/localtime:ro

This option allows you to use the same time zone in the container as that used in the Docker node — at the same time the file is integrated as read only (ro).

--restart always

A container does not normally restart automatically after it has been stopped. With this option you can ensure that it always starts again automatically. However, if you manually stop a container, it will only be restarted if the Docker daemon restarts or the container itself is restarted manually.

checkmk/check-mk-raw:2.0.0-latest

The Checkmk image label in the <repository>:<tag> format. The exact labels can be read out with the command docker images.

After all needed files have been loaded and the container has been started, you should access the GUI in Checkmk via http://localhost:8080/cmk/check_mk/:

Checkmk login dialogue.

You can now for the first time log in and try Checkmk out. You will find the provisional password for the cmkadmin account in the logs that are written for this container (the output is abbreviated to the essential information here in this example):

root@linux$ docker container logs monitoring
Created new site cmk with version 2.0.0.cre.

  The site can be started with omd start cmk.
  The default web UI is available at http://73a86e310b60/cmk/

  The admin user for the web applications is cmkadmin with password: 2JLysBmv
  For command line administration of the site, log in with 'omd su cmk'.
  After logging in, you can change the password for cmkadmin with 'htpasswd etc/htpasswd cmkadmin'.

Note: The URL displayed in the log for accessing the web interface with the ID of the container is only known within the container and is not suitable for access from outside in the web browser.

3.1. Short-lived containers

If you are sure that the data in the Checkmk container site should only be available in this special container, you can either refrain from assigning a persistent data storage to the container, or you can automatically remove this storage when the container is stopped.

To go without persistent storage, simply omit the -v /omd/sites option:

root@linux$ docker container run -dit -p 8080:5000 --tmpfs /opt/omd/sites/cmk/tmp:uid=1000,gid=1000 --name monitoring -v /etc/localtime:/etc/localtime:ro --restart always checkmk/check-mk-raw:2.0.0-latest

To create a persistent storage and remove it automatically when the container stops, use the following command

root@linux$ docker container run --rm -dit -p 8080:5000 --tmpfs /opt/omd/sites/cmk/tmp:uid=1000,gid=1000 -v /omd/sites --name monitoring -v /etc/localtime:/etc/localtime:ro checkmk/check-mk-raw:2.0.0-latest

This command — unlike the previous one — has only two other options:

  • Use the --rm option at the start to pass the command that the data storage for the container should also be removed when the container stops. This saves you having to tidy-up manually if you have many short-lived Checkmk containers.

    Important: When stopping, the container itself is completely removed!

  • The -v /omd/sites option is altered compared to the above. It no longer contains a self-assigned name, otherwise the data storage will not be deleted correctly.

4. Installation of the Enterprise Editions

CEE You can also run the Enterprise Editions in a Docker container. The images of the Enterprise Editions are not freely-available through Docker Hub. Download the desired edition and version from the Checkmk download page (for the Free Edition) or from the Checkmk customer portal.

Load the image from the downloaded tar archive file into Docker:

root@linux$ docker load -i check-mk-enterprise-docker-2.0.0p5.tar.gz
9e77dbc9fb80: Loading layer [==================================================>]  2.048kB/2.048kB
333c8e825260: Loading layer [==================================================>]  305.6MB/305.6MB
23a76a052da6: Loading layer [==================================================>]  175.7MB/175.7MB
f8583c4a8a97: Loading layer [==================================================>]  758.4MB/758.4MB
789d4e45d714: Loading layer [==================================================>]  6.656kB/6.656kB
Loaded image: checkmk/check-mk-enterprise:2.0.0p5

You can then start the container with a very similar command to that described above. Just take care that you use the name of the Loaded image from the previous command output in the following start command, so in this example checkmk/check-mk-enterprise:2.0.0p5:

root@linux$ docker container run -dit -p 8080:5000 --tmpfs /opt/omd/sites/cmk/tmp:uid=1000,gid=1000 -v monitoring:/omd/sites --name monitoring -v /etc/localtime:/etc/localtime:ro --restart always checkmk/check-mk-enterprise:2.0.0p5
f00d10fcb16313d3539065933b90c4dec9f81745f3d7283d794160f4f9b28df1

After starting the container, you can log in to the Checkmk web interface as described at the Installation of the Raw Edition.

5. Update

How to update Checkmk in a Docker container is described in the Updates and Upgrades article.

6. Uninstallation

When uninstalling, remove the Docker container and optionally the data created when the container was created.

Have the Docker containers listed:

root@linux$ docker container ls -a
CONTAINER ID   IMAGE                                 COMMAND                  CREATED          STATUS                    PORTS                              NAMES
9a82ddbabc6e   checkmk/check-mk-enterprise:2.0.0p5   "/docker-entrypoint.…"   57 minutes ago   Up 53 minutes (healthy)   6557/tcp, 0.0.0.0:8080->5000/tcp   monitoring

Take over the displayed CONTAINER ID from the command output for the next commands.

First stop the container and then remove it:

root@linux$ docker container stop 9a82ddbabc6e
9a82ddbabc6e
root@linux$ docker container rm 9a82ddbabc6e
9a82ddbabc6e

If you created the container with the -v monitoring:/omd/sites option, you can also remove the Docker volume created by this: docker volume ls displays the volumes and docker volume rm <VOLUME NAME> deletes the volume.

Finally, you can remove the image in a similar way: with docker images you get the list of images and docker rmi <IMAGE ID> removes the selected image.

On this page