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 scenario 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 virtualization 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 option 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, especially in this case verify whether the Docker/Container tool is the best solution for 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 contains the Debian Linux operating system in addition to Checkmk:
Checkmk Raw Edition
Checkmk Enterprise Editions
Checkmk download page (for the Free Edition), Checkmk customer portal
Note: Deployment in Docker Hub allows you to download and install with a single 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.
To execute the commands presented in this article you will need a working Docker Engine installation and basic knowledge of its use.
3. Installation of the Raw Edition
Getting started with the 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
root@linux# docker container run -dit -p 8080:5000 -p 8000:8000 --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.1.0-latest Unable to find image 'checkmk/check-mk-raw:2.1.0-latest' locally 2.1.0-latest: Pulling from checkmk/check-mk-raw 6552179c3509: Pull complete 5a25c1702974: Pull complete 1c5c13e7b7c2: Pull complete 665c930705aa: Pull complete 597c556025e7: Pull complete fe710cb5a7c0: Pull complete Digest: sha256:21be9d9ded25c498834009bcb890ef678fbcdabbc5b31a168f56ab4051b9a813 Status: Downloaded newer image for checkmk/check-mk-raw:2.1.0-latest b75e2e7d8039e73cc6e57ff09d28b4e6bccc91dbc7a85e55a3062e5fd14f596a
Some more information on the available options:
By default the container’s web server listens on port 5000. In this example port 8080 of the Docker node will be published 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:
Since Checkmk 2.1.0 you also have to publish the port for the Agent Receiver in order to be able to register the agent controller.
For optimal performance, you can use a temporary file system directly in the RAM of the Docker node. The path for this file system is specified with this option. If you change the site ID this path must also be edited accordingly.
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
This defines the name of the container. This name must be unique and may not be used again on the Docker node.
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 (
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.
The Checkmk image label in the <repository>:<tag> format. The exact labels can be read out with the command
After all needed files have been loaded and the container has been started, you should access the GUI in Checkmk via
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.1.0p17.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 'cmk-passwd cmkadmin'.
Note: The URL displayed in the log for accessing the web interface with the ID of the container is only recognized 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 -p 8000:8000 --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.1.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 -p 8000:8000 --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.1.0-latest
This command — unlike the previous one — has only two other options:
--rmoption 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!
-v /omd/sitesoption 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
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.1.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.1.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
root@linux# docker container run -dit -p 8080:5000 -p 8000:8000 --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.1.0p5 f00d10fcb16313d3539065933b90c4dec9f81745f3d7283d794160f4f9b28df1
After starting the container, you can log in to the Checkmk web interface as described at the Installation of the Raw Edition.
How to update Checkmk in a Docker container is described in the Updates and Upgrades article.
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 b75e2e7d8039 checkmk/check-mk-raw:2.1.0-latest "/docker-entrypoint.…" 2 minutes ago Up 2 minutes (healthy) 6557/tcp, 0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 0.0.0.0:8080->5000/tcp, :::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:
docker images you get the list of images and
docker rmi <IMAGE ID> removes the selected image.