Install Uptime Kuma with Docker Compose

Uptime Kuma is a monitoring dashboard with a drag-and-drop monitor list, ~90 notification integrations, certificate expiry alerts, and a public status page. It tells you in ten seconds whether the thing you just deployed is actually up, which is the fastest feedback loop available.

What it is

HTTP, TCP, DNS, ping, MQTT, Postgres, Redis, Docker container, and a lot more monitor types, all with configurable intervals, retries and thresholds. It keeps a 90-day history, groups monitors into status pages, and pushes to Discord, Slack, Telegram, email, or anything with a webhook.

Before you start

• Monitoring from the same host that serves the traffic proves very little — if the box reboots, Kuma is down too. Point at least a few monitors at the external URL.
• Default interval is 20 seconds across every monitor. Twenty monitors is 86,400 HTTP requests a day, which is fine locally and rude if you point them at someone else's server.
• Use the Docker socket monitor type sparingly. It can be a genuinely useful canary, but it also means the container can enumerate everything you're running.

1 — Write the compose file

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: always
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      TZ: UTC
    healthcheck:
      test: ["CMD", "node", "/app/monitor/extra/healthcheck.js"]
      interval: 30s
      timeout: 5s
      retries: 3

2 — Start it

mkdir -p ~/services/uptime-kuma/data
cd ~/services/uptime-kuma
docker compose up -d
docker compose logs -f uptime-kuma | grep -i "listening\|error"

3 — First-run setup

1. Create the admin account at http://yourhost:3001. There is no default — the first account you make is the admin, and Kuma refuses to start without one.
2. Add a notification channel before your first monitor. Settings → Notifications, pick Discord or Telegram, and send a test. Alerting on an alerting system is how you end up not being told when the alerting system breaks.
3. Add monitors. For each service: an HTTP monitor on its public URL, plus a Docker Container monitor so you learn about a crash loop before your users do.
4. Set up a status page under Status Pages. Even a private one is useful, and it doubles as a simple "is anything down right now" page you can check from your phone.
5. Add certificate monitors for the domains you care about. Expiry alerts are the single most time-saving feature here — a lapsed cert is an outage with a confusing cause.

4 — Habit that pays off

# confirm Kuma is monitoring from outside your own network
curl -s https://status.example.com/api/heartbeat/up | jq

# what is it actually polling?
docker exec uptime-kuma ls /app/data