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

1. Access the web UI at http://your-server:8080/cmk/check_mk/

2. Log in with:

   • Username: cmkadmin
   • Password: the value you set in CMK_PASSWORD

3. 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”

4. 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:

1. Go to Setup → Hosts → Add host
2. Under “Agent”, select “No agent, SNMP only”
3. Enter the SNMP community string
4. 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.

Related

• Checkmk vs Grafana: Monitoring Compared
• Checkmk vs Prometheus: Which Monitoring Stack?
• Best Self-Hosted Monitoring Tools
• Checkmk vs Zabbix
• Prometheus vs Zabbix
• How to Self-Host Zabbix
• How to Self-Host Grafana
• Self-Hosted Alternatives to Datadog
• Self-Hosted Alternatives to New Relic
• Docker Compose Basics
• Reverse Proxy Setup