1. The basics
Docker allows you to install Checkmk within a lightweight, self-contained container environment. In this article, we will guide you through the setting up of Checkmk in Docker, and show you some tricks that can make life with Checkmk in Docker easier.
 |
Checkmk provides official Docker images, but has no control over the characteristics of the host system on which you set up the corresponding containers.
The known advantages and disadvantages of container environments apply here.
In special cases, unexpected performance issues may arise, for example if the host system’s kernel is significantly newer or older than the kernel expected by the Checkmk installation in the container.
In such cases, additional |
2. Prerequisites
To execute the commands presented in this article, you will need a working installation of Docker Engine and have a basic understanding of how to use it.
3. Obtaining a Checkmk image
To make it as easy as possible for you to use as a container, we provide separate images for each Checkmk edition:
|
|
Commercial editions |
When one of these images is started for the first time, not only is the appropriate container executed, but a monitoring site named cmk will also be set up and started.
This site will immediately be ready for a login with the user cmkadmin.
3.1. Images for Checkmk Raw
For Checkmk Raw, you can obtain the desired Docker image directly from Docker Hub.
If you have an Internet connection, the Docker Engine automatically searches Docker Hub for the image name you specify to create a container.
You can jump directly to the section Starting a Checkmk container.
Alternatively, download the image yourself from Docker Hub or from the Checkmk download page and store it on the system where you want to start a Checkmk Raw container.
Use docker load -i check-mk-*.tar.gz to make the image file available for the Docker Engine on your Docker node:
root@linux# docker load -i check-mk-*.tar.gz
346f14bf17b9: Loading layer [==================================================>] 80.41MB/80.41MB
87334b162001: Loading layer [==================================================>] 2.048kB/2.048kB
4c6fcf6a2c87: Loading layer [==================================================>] 335.7MB/335.7MB
1ba0c3ef2749: Loading layer [==================================================>] 279.7MB/279.7MB
bebf82ffc112: Loading layer [==================================================>] 1.291GB/1.291GB
88b55249828a: Loading layer [==================================================>] 7.168kB/7.168kB
Loaded image: checkmk/check-mk-raw:2.4.0p103.2. Images for the commercial editions
The images for commercial editions are not freely available in Docker Hub.
You can either download the desired image manually and store it on your Docker node, or you can have the Docker engine itself download the image from the designated Checkmk Docker registry.
To download manually, find the edition and version you want at the Checkmk download page or at the Checkmk customer portal.
After downloading, use docker load -i as described in the Images for Checkmk Raw section.
To have the image downloaded from the Docker Engine, first log in to the Checkmk Docker registry with your customer portal login. To log in, use Docker’s credential store or the following command:
root@linux# docker login registry.checkmk.com --username myusername
Password:
Login SucceededAfter successfully logging in, the Docker Engine can access the image for the desired version via the registry. To do this, specify the full path to the desired image when starting the container. The Docker Engine then checks whether the image is already available locally and, if not, downloads it automatically.
For version 2.4.0p10 of Checkmk Enterprise, for example, specify the full path for the image as follows when starting the container:
registry.checkmk.com/enterprise/check-mk-enterprise:2.4.0p10
For the corresponding versions of Checkmk Cloud or Checkmk MSP, replace all occurrences of enterprise in this path with cloud or managed, respectively.
4. Starting a Checkmk container
You can start Checkmk images either with docker compose and a compose file or with docker container run, specifying a set of parameters.
Which option you choose depends on your specific usage case.
4.1. Starting with docker compose
The following example shows the variant using docker compose, with which only a little setup effort makes it possible to start additional containers in parallel.
In the compose.yaml file, you use parameters to describe the desired properties for the Docker container to be started.
Several containers can also be described here, which are then started together.
The following example of a suitable compose.yaml file shows the parameters for starting a single Checkmk container.
The parameters contained and their values are explained below.
services:
checkmk:
image: "checkmk/check-mk-raw:2.4.0-latest"
container_name: "monitoring"
environment:
- CMK_PASSWORD=mypassword
- TZ=Europe/Berlin
volumes:
- monitoring:/omd/sites
tmpfs:
- /opt/omd/sites/cmk/tmp:uid=1000,gid=1000
ports:
- 8080:5000
- 8000:8000
restart: always
volumes:
monitoring:More information about the options used:
| Option | Description |
|---|---|
|
Self-defined descriptive name for the Docker service for which the Checkmk container is to be started. |
|
Name of the Checkmk image in the format |
|
Self-chosen descriptive name for the container. This name must be unique and may not be used a second time on the Docker node. |
environment: - CMK_PASSWORD=mypassword - TZ=Europe/Berlin |
Use the environment variable
|
volumes: - monitoring:/omd/sites |
This specification binds the site’s data in this container to a persistent location in the file system of the Docker node.
The volume named |
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. With this option, you specify the path to this file system. If you change the ID of the site this path must also be updated accordingly. |
ports: - 8080:5000 - 8000:8000 |
The container’s web server listens on port 5000 by default.
In this example, port 8080 of the Docker node is bound to port 5000 of the container so that its web interface is accessible from the outside.
If you do not have another container or process that uses the standard HTTP port 80, you can also bind the container to it.
In this case, the option would look like this:
For certain scenarios that go beyond the basic functionality of Checkmk, additional ports must be explicitly enabled. This applies, for example, to access to Livestatus via TCP in distributed monitoring or the use of Event Console within a Checkmk container. An overview of the relevant ports can be found in the Ports article. |
|
Normally, a container does not restart when it is stopped. This option ensures that it does restart automatically. However, if you stop a container manually, it will only restart when the Docker daemon restarts or the container itself is restarted manually. |
volumes: monitoring: |
All volumes required within services appear here.
In this case, this is only the |
In addition to the checkmk service, in your compose.yaml file you can define additional services that are to be started in the same container group.
Once you have described everything as desired, you can create and start the containers.
To do this, run docker compose up in the directory where your compose.yaml file is located.
With docker compose up -d (for detached), the containers are started in the background.
docker compose up ensures that all containers and their associated volumes are created properly.
If you have not yet downloaded an image and stored it on your system, executing docker compose up will take a few minutes, as the specified image will be loaded from Docker Hub (only possible for Checkmk Raw) or from the Checkmk Docker registry at this point.
The output here is based on a scenario in which the image was prepared with docker load -i.
root@linux# docker compose up
[+] Running 3/3
✔ Network cmk_compose_default Created 0.0s
✔ Volume "cmk_compose_monitoring" Created 0.0s
✔ Container monitoring Created 0.0s
Attaching to monitoring
monitoring | ### CREATING SITE 'cmk'
monitoring | Generating configuration for core (type nagios)...
monitoring | Precompiling host checks...OK
monitoring | Adding /opt/omd/sites/cmk/tmp to /etc/fstab.
monitoring | Going to set TMPFS to off.
monitoring | Updating core configuration...
monitoring | Executing post-create script "01_create-sample-config.py"...OK
monitoring | Executing post-create script "02_cmk-compute-api-spec"...OK
monitoring | Executing post-create script "03_message-broker-certs"...OK
monitoring | Adding /opt/omd/sites/cmk/tmp to /etc/fstab.
monitoring | Going to set TMPFS to off.
monitoring | Skipping Apache restart.
monitoring | Created new site cmk with version 2.4.0p10.cre.
monitoring |
monitoring | The site can be started with omd start cmk.
monitoring | The default web UI is available at http://2403d4ed552d/cmk/
monitoring |
monitoring | The admin user for the web applications is cmkadmin with password: mypassword
monitoring | For command line administration of the site, log in with 'omd su cmk'.
monitoring | After logging in, you can change the password for cmkadmin with 'cmk-passwd cmkadmin'.
monitoring |
monitoring | ### STARTING XINETD
monitoring | * Starting internet superserver xinetd
monitoring | ...done.
monitoring | ### STARTING SITE
monitoring | Starting agent-receiver...OK
monitoring | Starting mkeventd...OK
monitoring | Starting rrdcached...OK
monitoring | Starting redis...OK
monitoring | Starting npcd...OK
monitoring | Starting automation-helper...OK
monitoring | Starting ui-job-scheduler...OK
monitoring | Starting nagios...OK
monitoring | Starting apache...OK
monitoring | Starting crontab...OK
monitoring | ### STARTING CRON
monitoring | ### CONTAINER STARTEDStop running containers with docker compose stop.
To restart containers that have already been created, run docker compose start.
View the output of the monitoring container with docker container logs monitoring.
With docker inspect monitoring get detailed information about the container — the volumes it includes, for example.
4.2. Start with docker container run
As an alternative to running with docker compose, you can start the Checkmk image with docker container run.
To do this, pass the information from the compose.yaml file as parameters.
The following command creates the same container with the same properties as in the example just shown. The output shown is based on a scenario in which the image has not yet been downloaded manually.
root@linux# docker container run -dit \
--name monitoring \
-e CMK_PASSWORD='mypassword' \
-e TZ='Europe/Berlin' \
-v monitoring:/omd/sites \
--tmpfs /opt/omd/sites/cmk/tmp:uid=1000,gid=1000 \
-p 8080:5000 \
-p 8000:8000 \
--restart always \
checkmk/check-mk-raw:2.4.0-latest
Unable to find image 'checkmk/check-mk-raw:2.4.0-latest' locally
2.4.0-latest: Pulling from checkmk/check-mk-raw
215ed5a63843: Pull complete
942691e22878: Pull complete
fafdf3fa2522: Pull complete
1888d204a5e5: Pull complete
c126aa904d34: Pull complete
b469f01932b5: Pull complete
Digest: sha256:bbabed3f4f5e88775f872bcf0f1df36660e13d0ebf613e4e6141f4c81e5c6354
Status: Downloaded newer image for checkmk/check-mk-raw:2.4.0-latest
c850572de41592afff9de610d1ef3faecb267bf4fbccf2a9d8dae92dec11aacbHere the container is run in detached mode (-d).
To view the output from the container, use docker container logs monitoring.
For detailed information about the container, use docker inspect monitoring.
|
When starting with |
4.3. Additional setup options
The examples shown so far are for the simple setup of Checkmk containers. Several additional options are available for special application scenarios.
HTTPS
You can also secure your site’s web interface via HTTPS within a Docker container. The common practice for this is to use a reverse proxy, which acts as the interface for HTTP(S) connections between the containers in your system and the outside world. This proxy can ensure that only HTTPS connections are accepted or passed on to the Checkmk container.
If you use a reverse proxy, do not explicitly enable any ports when starting your Checkmk container. Instead, all incoming and outgoing connections will then be handled exclusively via the reverse proxy.
Additional environment variables
The table shows all Checkmk-specific environment variables that you can use when starting the container to set up your container as desired.
To do this, specify the variable values in the compose file or in the parameter list when calling docker container run in the same form as the previously mentioned environment variables CMK_PASSWORD and TZ.
|
Self-defined name of the Checkmk site to be created within the container, if you want to deviate from the default site name |
|
Setting for using Livestatus via TCP.
If you select |
|
Address of a mail relay server provided by you (e.g., |
5. Using Checkmk in the running container
Once all the necessary files have been loaded and the container has started, you should be able to access the Checkmk GUI via http://localhost:8080/cmk/check_mk/ or via the address of the Docker node:
You can now log in for the first time and try out Checkmk.
To access your site within the container via the command line, log in to the container as an site user.
In Checkmk, this user always has the same name as the site it manages.
Use the following command to open an interactive Bash session in the monitoring container and log in as user cmk:
root@linux# docker container exec -it -u cmk monitoring bashYou can then pass your commands to the site.
6. Update
How to update Checkmk in the Docker container is described in the article Updates and Upgrades.
7. Uninstallation
If you no longer need a container, you can remove it and, if necessary, delete its associated volumes. The commands for this can be found in the following sections.
7.1. Uninstalling with docker compose
To remove a container, run docker compose down (with the container running) or docker compose rm (with the container stopped).
root@linux# docker compose down
[+] Running 2/2
✔ Container monitoring Removed 6.3s
✔ Network cmk_compose_default Removed 0.1sIf you add the -v option, the associated volumes on the Docker node will also be removed along with the container.
7.2. Uninstalling after starting with docker container run
You can stop a container named monitoring that was started with docker container run using docker container stop monitoring. You can then remove the container using docker rm monitoring. You can delete a volume named monitoring that you no longer need after removing its associated container using docker volume rm monitoring.
7.3. Deleting the Checkmk image
If you no longer wish to use the selected Checkmk image, you can remove it with docker rmi myimageid.
The command docker images lists all existing images.
Identify the image you want to delete and add the corresponding image ID to your call to docker rmi.