Self-Hosting Checkmk with Docker Compose

What Is Checkmk?

Checkmk is an enterprise-grade infrastructure monitoring platform that monitors servers, network devices, applications, and cloud services. It replaces commercial solutions like Datadog and PRTG with a self-hosted platform that handles auto-discovery, agent-based and agentless monitoring, alerting, and reporting. The Raw Edition (open source) monitors thousands of hosts with no licensing costs.

Prerequisites

A Linux server (Ubuntu 22.04+ recommended) with at least 2 GB of RAM
Docker and Docker Compose installed (guide)
10 GB of free disk space
A domain name (optional, for remote access)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  checkmk:
    image: checkmk/check-mk-raw:2.3.0p44
    container_name: checkmk
    restart: unless-stopped
    environment:
      - CMK_PASSWORD=ChangeThisStrongPassword
      - CMK_SITE_ID=cmk
      - TZ=UTC
    ports:
      - "8080:5000"   # Web UI
      - "8000:8000"   # Agent receiver (auto-registration)
    volumes:
      - checkmk_data:/omd/sites
    tmpfs:
      - /opt/omd/sites/cmk/tmp:mode=1777

volumes:
  checkmk_data:

Key configuration choices:

Setting	Purpose
`CMK_PASSWORD`	Admin login password. Change this before deploying
`CMK_SITE_ID`	Site identifier used in URL paths. Default `cmk` works for single-site setups
Port 8080→5000	Maps the web UI to port 8080 on the host
Port 8000	Agent receiver for automatic host registration
`tmpfs` mount	Temporary files in RAM for better performance

Start the stack:

docker compose up -d

First startup takes 30-60 seconds while Checkmk initializes the site.

Initial Setup

Access the web UI at http://your-server:8080/cmk/check_mk/
Log in with:
- Username: cmkadmin
- Password: the value you set in CMK_PASSWORD
Monitor the Docker host — add your first host:
- Navigate to Setup → Hosts → Add host
- Enter the hostname or IP of your server
- Save and run “Activate pending changes”
Install agents on remote hosts — Checkmk uses agents for detailed monitoring:
- Go to Setup → Agents → Agent Bakery (Enterprise) or download agents from Setup → Agents
- Install the agent on each host you want to monitor
- Hosts with agents are auto-discovered

Configuration

Agent-Based Monitoring

Install the Checkmk agent on Linux hosts:

# Download from your Checkmk instance
wget http://your-server:8080/cmk/check_mk/agents/check-mk-agent_2.3.0p44-1_all.deb
sudo dpkg -i check-mk-agent_2.3.0p44-1_all.deb

The agent exposes monitoring data on port 6556 (TCP). Checkmk polls it every 60 seconds.

Agentless (SNMP) Monitoring

For network devices that don’t support agents:

Go to Setup → Hosts → Add host
Under “Agent”, select “No agent, SNMP only”
Enter the SNMP community string
Save and activate changes

Email Notifications

Configure outbound email for alerts:

environment:
  - MAIL_RELAY_HOST=smtp.example.com

Or configure notification rules in the web UI under Setup → Events → Notifications.

Distributed Monitoring

For multi-site setups, enable Livestatus TCP:

environment:
  - CMK_LIVESTATUS_TCP=on
ports:
  - "6557:6557"   # Livestatus TCP

Connect remote Checkmk sites to the central site through Setup → General → Distributed Monitoring.

SNMP Trap and Syslog Receivers

For network device event monitoring:

ports:
  - "162:162/udp"   # SNMP traps
  - "514:514/tcp"   # Syslog (TCP)
  - "514:514/udp"   # Syslog (UDP)

Enable the Event Console in the web UI under Setup → Events → Event Console.

Reverse Proxy

For Nginx Proxy Manager, create a proxy host pointing to http://checkmk:5000. The URL path /cmk/check_mk/ must be preserved.

For Caddy:

monitoring.example.com {
    reverse_proxy checkmk:5000
}

See Reverse Proxy Setup for detailed configuration.

Backup

Back up the data volume for full disaster recovery:

# Stop Checkmk for a consistent backup
docker compose stop checkmk

# Back up the data volume
docker run --rm -v checkmk_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/checkmk-backup.tar.gz /data

# Restart
docker compose start checkmk

The checkmk_data volume contains all configuration, monitoring history, and user settings.

See Backup Strategy for a comprehensive approach.

Troubleshooting

Web UI Returns 404

Symptom: http://your-server:8080/ shows a blank page or 404. Fix: The URL must include the site path: http://your-server:8080/cmk/check_mk/. The cmk in the path matches your CMK_SITE_ID.

Agent Connection Refused

Symptom: Checkmk shows “Connection refused” for a monitored host. Fix: Verify the agent is installed and listening: ss -tlnp | grep 6556. If using a firewall, open port 6556 TCP. If using Docker networking, ensure the host is reachable from the Checkmk container.

Container Exits Immediately

Symptom: Container stops right after starting. Fix: Check for port conflicts on 5000, 8000, or 6557. Also verify the tmpfs path matches your CMK_SITE_ID: /opt/omd/sites/<SITE_ID>/tmp.

High Memory Usage

Symptom: Checkmk uses excessive RAM with many monitored hosts. Fix: Reduce check interval frequency in Setup → Services → Check intervals. Disable unused check plugins. For 500+ hosts, consider 4+ GB RAM.

Resource Requirements

Resource	Up to 50 hosts	Up to 500 hosts	500+ hosts
RAM	2 GB	4 GB	8+ GB
CPU	2 cores	4 cores	8+ cores
Disk	10 GB	50 GB	100+ GB

Resource usage scales with the number of monitored hosts and check frequency. The Raw Edition handles hundreds of hosts on modest hardware.

Verdict

Checkmk is the best self-hosted option for enterprise-style infrastructure monitoring. Its auto-discovery, agent-based monitoring, SNMP support, and built-in alerting cover use cases that simpler tools like Uptime Kuma or Beszel can’t touch. The web UI is functional if not beautiful, and the configuration-as-code approach (WATO) makes managing hundreds of hosts practical.

The trade-off is complexity. Checkmk has a steeper learning curve than lightweight monitors. If you’re monitoring 5-10 services, it’s overkill — use Uptime Kuma or Beszel instead. If you’re monitoring 50+ hosts across servers, switches, and services, Checkmk and Zabbix are your two best options. Checkmk has the edge in auto-discovery and agent management; Zabbix has a larger community and more extensive documentation.

Frequently Asked Questions

Is the Checkmk Raw Edition free?

Yes. The Raw Edition is fully open-source under the GPLv2 license with no host limits, no check limits, and no licensing fees. It includes agent-based monitoring, SNMP, auto-discovery, alerting, and the full web UI. The Enterprise and Cloud editions add features like distributed monitoring, Agent Bakery, and professional support.

How does Checkmk compare to Zabbix?

Both are enterprise-grade monitoring platforms. Checkmk has better auto-discovery and a simpler agent deployment workflow. Zabbix has a larger community, more documentation, and handles SNMP trap processing natively. Checkmk’s web UI is more modern. Both handle thousands of hosts. Choose Checkmk for faster setup and auto-discovery; choose Zabbix for the largest community support and template ecosystem.

Can I monitor Docker containers with Checkmk?

Yes. Install the Checkmk agent on the Docker host and it auto-discovers running containers. The agent reports container status, resource usage, and image information. The Docker-specific check plugins are included in the agent package.

Why is the URL path /cmk/check_mk/ instead of just /?

Checkmk uses site-based URLs where cmk is your CMK_SITE_ID. This allows running multiple Checkmk sites on the same server. The path format is /SITE_ID/check_mk/. If you set CMK_SITE_ID=mysite, the URL becomes /mysite/check_mk/.

How many hosts can the Raw Edition monitor?

The Raw Edition has no artificial host limits. On a server with 2 GB RAM and 2 CPU cores, it comfortably handles 50-100 hosts. With 4-8 GB RAM, it handles 500+ hosts. The bottleneck is usually check frequency and the number of monitored services per host rather than raw host count.

Do I need to install agents on every monitored server?

No. Checkmk supports multiple monitoring methods: agent-based (most detailed data), SNMP (network devices), and agentless HTTP checks. For Linux and Windows servers, the agent provides the richest monitoring data. For network switches, routers, and printers, SNMP works without any agent.