Install checkmk with Docker Compose

It’s sometimes difficult to work out what is using resources over time. This application provides an easy to use service to monitor infrastructure.

In this post, checkmk is installed using Docker Compose to monitor a Linux system and (optionally) its Docker containers. The first steps install Docker Compose, then checkmk is setup. The installation host is Ubuntu, however since most of the magic happens in Docker, the Linux distribution is not really important.

0 . Latest updates and prerequisites.

2024.11.23 – First draft, Ubuntu 24.04 Server.

Check back for updates, if you run into trouble. Leave a comment if the post is missing some detail.

Sudo permissions are required on both the server and any clients that need to be monitored.

1 . Install Docker Compose.

Assuming the Linux server is up-to-date and Internet connectivity is trouble-free, as a sudo user, install docker-compose-v2.

sudo apt install docker-compose-v2

Create a location for all the docker files.

sudo mkdir /opt/docker

Set the owner and permissions for the user docker will be running as. This is not a common step, however, it is good practice to have as little as possible running as root. In this case´, I have a user called localadmin who the services will run as:

sudo chown localadmin:localadmin /opt/docker
sudo chmod 775 /opt/docker

It is possible to test the docker installation is working and all dependencies are in place with a simple “Hello World”:

docker run hello-world

Some output will indicate the installation is either working or an error message will indicate it’s not.

2 . Create Environment Settings and Variables.

Create a simple environment file with some reusable settings:

sudo nano /opt/docker/.env

And add the following details to the file, substituting as you need. This is an optional but recommended step:

TIMEZONE="Europe/Berlin"
ROOT="/opt/docker"

Docker Compose will look for this file in the directory it is run from.

3 . Install checkmk.

The documentation for checkmk includes instructions for running as docker, directly from the command line, but with some experience, it is easy to convert this to a compose file for the sake of legibility and good documentation practices:

sudo nano /opt/docker/docker-compose.yml

The configuration used here is this, substitute some settings if necessary:

services:
  checkmk:
    image: checkmk/check-mk-raw:2.3.0-latest
    container_name: checkmk
    environment:
      - TZ=${TIMEZONE}
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ${ROOT}/checkmk:/omd/sites
    networks:
      - backend
    ports:
      - 8080:5000
      - 8000:8000
    restart: unless-stopped

networks:
  backend:
    driver: bridge

Port 8080 is the web interface. Recent versions of checkmk use port 8000 for agent registration.

Notice, this configuration specifies a network called “backend”. Recent versions of docker require a non-default network otherwise name resolution, in the docker network, may not be honoured.

The admin username and password is put out in the log file, it can be retrieved from the container:

docker container logs checkmk

The output contains the login details:

Created new site cmk with version 2.3.0p21.cre.

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

  The admin user for the web applications is cmkadmin with password: wGIq9MfegEtPt
  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'.

Open a web browser to the host with the port specified above, in this case, 8080:

Login with the username cmkadmin and the password from the log:

4 . Install a Linux agent.

The monitoring service has no clients, firstly it would be good to keep track of the server that is hosting this service. checkmk can use a service such as SNMP to monitor, but in this case, an agent is installed.

The agents are included in the base product:

Download the agent files to a temporary location on the system that will be monitored, substitute the IP address as required:

wget http://172.16.30.201:8080/cmk/check_mk/agents/check-mk-agent_2.3.0p21-1_all.deb

Install the client agent from the terminal of any Linux system, in this case, Ubuntu:

sudo dpkg -i check-mk-agent_2.3.0p21-1_all.deb

At the web interface, add the host to be monitored:

Insert details, click “save and run connection tests”, then, if successful, on the following dialogue, click “save and go to host properties”:

In the host properties dialogue, there is an option to scan for services. It might be first time scanning takes a few minutes before a successful outcome:

Metrics not required can be removed with the little red “x” icon, otherwise click “accept all”.

Return to the default dashboard to see nothing is monitored, because the services must be restarted. Click the little yellow cautionary icon in the top right to acknowledge the restart is required:

Once the red restart icon is clicked, the dashboard displays the newly installed agent’s details:

It is possible to click through and see some data after a short while, usually about 15 minutes.

5 . Install the Docker plug-in.

The agent installation above does not have visibility of Docker containers by default, to install this awareness, first make sure python3 is installed (it should have been installed with Docker):

sudo apt install python3

Download the plugin from the checkmk site to a temporary location:

Substitute the address as necessary:

wget http://172.16.30.201:8080/cmk/check_mk/agents/plugins/mk_docker.py

Install the agent docker add-on:

sudo install -m 0755 mk_docker.py /usr/lib/check_mk_agent/plugins

Install pip3 if not already installed:

sudo apt install python3-pip

Then use pip3 to install the python add-on for Docker:

sudo pip3 install docker

Download the default docker.cfg file to /etc/check_mk/docker.cfg:

By default, containers are monitored by there container_id, something that will not be easy to follow when the installation grows. It is highly recommended to change the default to the container name (and take care to use unique names in the future). In the docker.cfg file, change the line, container_id to “name”:

sudo nano /etc/check_mk/docker.cfg

# CONTAINER ID
# You can choose what to use as the container identifier. This will
# affect the name used for the piggyback host corresponding to the
# container, as well as items for services created on the node for each
# container.
# By default, the identifier is assumed to be the first 12 characters
# of the container UUID. You can choose to use the full ID or the containers
# name instead. Allowed values are "short" (the default), "long" and "name".
container_id: name

Run the service discovery under the docker host and “Docker containers” will appear in the discovery screen:

Again, add and remove services for which metrics are required with either the “+” or “X” icons.

For each Docker container to be monitored, create a host with only the container name as the host address:

Save and run service discovery. After a few seconds, the container’s services are listed. There will be some overlap between what resources the host has and the resources the container can “see”, it is therefore a good idea to monitor only the services required.

The host is visible once the changes are accepted and service refreshed (yellow exclamation in top left corner):

Docker containers are treated as individual hosts within the context of the host server. For example, the host server has 8GB of RAM, so too will the docker container:

6 . Supporting this blog.

This type of content takes a lot of effort to write. Each post is drafted, researched, then tested multiple times, even a simple step or detail might take more than a few hours to go from the idea to a published blog post.

Did you notice there are no adverts on this site, surely my typos give away this is not AI generated content?

If you feel I have saved you some time, you can support me by;

• hosting with DigitalOcean, like I do – click here to go to DigitalOcean.

• buying me a beer through PayPal – click here to go to PayPal.

©horsefreeglue.com, 2024. Unauthorized use and/or duplication of this material without express and written permission from this site’s author and/or owner is strictly prohibited. Excerpts and links may be used, provided that full and clear credit is given.