Uptime Kuma Docker Setup & Alerting Guide (Discord & Telegram)

Finding out your site is down because a client emailed you is the worst kind of monitoring. Uptime Kuma fixes that — it’s a free, self-hosted alternative to Pingdom and Better Uptime that pings your endpoints every 60 seconds and screams at you on Discord or Telegram when something breaks.

If you already built a production Docker Compose stack, this is the monitoring layer you add on top. Takes about ten minutes.

How Alerting Flows

flowchart TD
    MonitoredTarget[Production Endpoint / Service] -->|HTTP GET every 60s| KumaEngine[Uptime Kuma Engine]
    
    KumaEngine -->|Status 200 OK| StateGreen[Healthy Green State]
    KumaEngine -->|Timeout / 5xx Error| RetryCheck{Retry 3 Times}
    
    RetryCheck -->|Success| StateGreen
    RetryCheck -->|Failure Confirmed| StateRed[Incident Red State]
    
    StateRed -->|Trigger Webhook| NotificationRouter[Notification Router]
    NotificationRouter -->|Instant Alert| Telegram[Telegram Bot Channel]
    NotificationRouter -->|Incident Card| Discord[Discord Webhook Channel]
    StateRed -->|Update Public UI| StatusPage[Public Status Page UI]

Kuma retries three times before firing an alert — saves you from false positives when your server hiccups for five seconds during a deploy.

Step 1: Deploy with Docker Compose

version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - "3001:3001"
    volumes:
      - uptime-kuma-data:/app/data

volumes:
  uptime-kuma-data:

mkdir -p /opt/uptime-kuma && cd /opt/uptime-kuma
docker compose up -d

Open http://<server-ip>:3001, create your admin account. The persistent volume keeps your monitors and alert configs across container restarts — don’t skip it.

Step 2: Add Monitors

Uptime Kuma supports four monitor types worth knowing:

To add your first monitor:

1. Click Add New Monitor
2. Select HTTP(s)
3. Enter your URL (https://example.com)
4. Set interval to 60 seconds
5. Save

You’ll see a real-time latency graph and uptime percentage bar within a minute. Add every production endpoint you care about — API, frontend, database proxy, the lot.

Pro tip: Monitor your monitoring. If Uptime Kuma itself goes down, nothing alerts you. Run a second instance elsewhere or use an external ping service to watch Kuma.

Step 3: Wire Up Discord and Telegram Alerts

Uptime Kuma supports 90+ notification providers. Discord and Telegram are the two I actually use.

Telegram setup

1. Message @BotFather on Telegram → create a bot → copy the Bot Token
2. Add the bot to your alert group → get the Chat ID (use @userinfobot or check the Telegram API)
3. In Kuma: Settings → Notification → Setup Notification
4. Select Telegram, paste Bot Token and Chat ID
5. Click Test — you should get a message in the group

Discord setup

1. In Discord: Server Settings → Integrations → Webhooks → New Webhook
2. Copy the Webhook URL
3. In Kuma: select Discord, paste the URL, save
4. Click Test

Assign notifications to monitors individually or set a default notification on each monitor. I put critical production endpoints on Telegram (phone buzzes) and staging on Discord (team channel, less urgent).

FAQ

How many monitors can one instance handle?

A 1 vCPU / 1 GB RAM VPS handles 200+ HTTP/TCP monitors at 60-second intervals without breaking a sweat. Uptime Kuma is lightweight — the bottleneck is your network, not CPU.

How do I put Uptime Kuma behind a custom domain with SSL?

Put Traefik or Nginx Proxy Manager in front of it. Route status.yourdomain.com → port 3001. Enable WebSocket support in your proxy config — Kuma’s dashboard uses WebSockets for live updates and breaks silently without it.

Can Kuma monitor Docker containers without exposing ports?

Yes. Mount the Docker socket read-only:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Then add a Docker Container monitor type. Kuma reads container state directly — useful for internal services that shouldn’t have public ports.

What to Read Next

• Production Docker Compose Stack — Traefik + Postgres stack to monitor
• Top 10 Self-Hosted DevOps Tools — Uptime Kuma in context with Portainer, Traefik, Coolify
• AWS Skill Builder & Azure Learn Free Badges — stack cloud credentials while you run your home lab