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.
 |
The use of Checkmk based on the images presented here is only supported within Docker itself. Other container environments compatible with Docker may work, but are not supported by Checkmk. In such cases, you use them at your own risk and they are not recommended for productive environments. |
3. Obtaining a Checkmk image
To make it as easy as possible for you to use Checkmk as a container, we provide separate images for each Checkmk Edition in various ways. The images from the different sources for an edition are identical.
|
— |
— |
||
|
— |
|||
|
— |
|||
|
— |
When one of these images is started for the first time, not only will the appropriate container be executed, but a monitoring site named cmk will also be set up and started.
This will be ready for immediate login with the user cmkadmin.
The official images are also freely available on various platforms for the Checkmk Cloud and Checkmk MSP commercial editions.
These editions of Checkmk can be tested with all features as part of a 30-day trial period.
If you do not purchase a license for the selected edition, you will be switched to the 'Free' license status after the trial period expires.
With this status, you can monitor up to 750 services and will be limited to a single site.
3.1. Automatically download images when starting a container for the first time
If an Internet connection is available, the Docker Engine automatically searches Docker Hub for the image name you specify when creating a container. For editions whose images are available in Docker Hub according to the above table, you can jump directly to the section Starting a Checkmk container.
Images for Checkmk Enterprise are stored in the Checkmk Docker Registry. Here the Docker Engine can automatically find and download images based on their full name and file path. However, you must first log in to the registry with your credentials from the Checkmk customer portal. To log in, use the Docker Credential Store or the following command:
After successfully logging in, the Docker Engine can access the Checkmk images 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.0p17 of Checkmk Enterprise, for example, specify the full path for the image when starting the container as follows:
registry.checkmk.com/enterprise/check-mk-enterprise:2.4.0p17
3.2. Downloading and preparing images manually
The images can also be downloaded as archive files and stored on the system where you want to start the container.
This can be useful, for example, if your Docker host does not have an Internet connection when the container is started.
Download the desired image and transfer the file to your Docker host using your preferred method.
Then use docker load -i to make the image file available to the Docker Engine on your system:
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.
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 You can read the names of existing images using the If you obtain the image from the Checkmk Docker registry, the image must be specified with its full path. |
|
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
If you do not want to set the time zone explicitly, you can alternatively adopt the time settings from the Docker host.
To do this, mount the file |
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 specify a different name when creating 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 are specified here.
In this case, this is only the |
In addition to the checkmk Docker Compose 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 container or containers.
To do this, run docker compose up in the directory where your compose.yaml file is located.
docker compose up ensures that all containers and their associated volumes are created properly.
With docker compose up -d (for detached), the containers are started in the background.
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 or from the Checkmk Docker registry at this point.
|
If an image with the specified name already exists on your Docker host, no new image will be downloaded — so your local image may already be out of date when you first start the container.
To ensure that you are working with the latest image, run |
The output here is based on a scenario in which the image was prepared with docker load -i.
Stop 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 shown above.
The output shown is based on a scenario in which the image has not yet been downloaded manually.
Optionally, you can force the download of the latest image by prefixing docker pull checkmk/check-mk-raw:2.4.0-latest.
Here 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 do this, use the cmkadmin user and the password you chose when creating the container.
If your site has a name other than cmk, edit the name in the URL.
To access your site within the container via the command line, log in to the container as the 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:
You 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).
If you add the -v option, the associated volumes on the Docker node will also be removed along with the container.
|
Only use the |
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.