Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 3: Self-Hosted Open-Source Docker Templates6 min readVerified

Production Uptime Kuma Docker Compose Setup with Traefik HTTPS & WebSocket Labels

Deploy Uptime Kuma v2 with Docker Compose behind Traefik v3 TLS. Includes WebSocket upgrade headers, read-only Docker socket container monitoring, and UFW-safe port binding.

TL;DR — Immediate Production Fix

Uptime Kuma relies on persistent Socket.IO WebSocket connections on internal port 3001 to render real-time latency graphs and status pages. When deploying Uptime Kuma behind Traefik or Nginx via Docker Compose, never publish `ports: - "3001:3001"` on `0.0.0.0` (which bypasses Linux UFW firewall rules and exposes the unencrypted dashboard publicly). Instead, route exclusively over an internal Docker proxy network with `traefik.http.services.uptime-kuma.loadbalancer.server.port=3001` and enable Trust Proxy inside Uptime Kuma settings.

Verified Root Causes in Production Environments

  • Publishing 0.0.0.0:3001:3001 Bypasses Host UFW Firewalls: Docker manipulates iptables nat PREROUTING chains directly, exposing port 3001 to the public internet even when ufw status shows port 3001 blocked.
  • WebSocket Connection Drops Behind Reverse Proxies: Missing Upgrade and Connection header forwarding or short proxy read timeouts cause the Uptime Kuma dashboard to infinitely show 'Cannot connect to the socket server'.
  • Unmounted /var/run/docker.sock When Monitoring Local Containers: Attempting to add a 'Docker Container' monitor inside Uptime Kuma fails unless the host Docker socket is mounted read-only.

1. Production docker-compose.yml With Traefik v3 TLS & Security Headers

To deploy Uptime Kuma securely on a single VPS or Coolify/Vexlo Cloud host, attach the container to your external `proxy` (or `coolify`) Docker network and omit public port publishing altogether. If you need local SSH tunnel access without a reverse proxy, bind strictly to `127.0.0.1:3001:3001`.

Mounting `/var/run/docker.sock:/var/run/docker.sock:ro` (read-only) allows Uptime Kuma to inspect the health of sibling containers (such as PostgreSQL, Redis, or your Next.js app) without exposing TCP ports.

For Indian SaaS engineering teams monitoring multi-region APIs, UPI payment gateway endpoints, and Docker containers across Mumbai, Delhi NCR, and Singapore, Uptime Kuma provides sub-20-second heartbeat intervals with native Telegram, Slack, Discord, and webhook alerting. However, because Uptime Kuma uses an embedded SQLite database under /app/data/kuma.db, high-frequency checks across 100+ monitors can cause database file bloat over several months.

Configure Uptime Kuma's built-in data retention policy (Settings -> Monitor History -> Keep data for 30 or 90 days) so nightly SQLite VACUUM jobs keep disk I/O low and prevent Socket.IO dashboard lag when loading historical ping charts over WebSocket connections.

docker-compose.yml
yaml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: always
    volumes:
      - uptime_kuma_data:/app/data
      # Optional: Mount Docker socket read-only to monitor sibling containers
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - proxy
    # Security best practice: Do NOT publish 0.0.0.0:3001:3001 publicly
    # ports:
    #   - "127.0.0.1:3001:3001"
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.kuma.rule=Host(`status.vexlo.cloud`)"
      - "traefik.http.routers.kuma.entrypoints=websecure"
      - "traefik.http.routers.kuma.tls=true"
      - "traefik.http.routers.kuma.tls.certresolver=letsencrypt"
      - "traefik.http.services.kuma.loadbalancer.server.port=3001"
    healthcheck:
      test: ["CMD-SHELL", "extra/healthcheck || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

volumes:
  uptime_kuma_data:

networks:
  proxy:
    external: true

2. Fixing WebSocket Disconnections in Nginx & Cloudflare Proxies

Traefik automatically upgrades HTTP/1.1 connections to WebSockets (`Upgrade: websocket`, `Connection: Upgrade`) out of the box. However, if you place Nginx in front of Uptime Kuma or proxy `status.yourdomain.com` through Cloudflare (orange cloud), missing upgrade headers will cause the UI to freeze on login.

In Nginx, explicitly add `proxy_set_header Upgrade $http_upgrade;` and `proxy_set_header Connection "upgrade";` inside the `location /` block, and enable 'Trust Proxy' inside Uptime Kuma -> Settings -> Reverse Proxy so real visitor IPs are logged.

nginx-uptime-kuma.conf
nginx
server {
    listen 443 ssl http2;
    server_name status.vexlo.cloud;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400s;
    }
}

3. Zero-Downtime Upgrades & Automated SQLite Volume Backups

Uptime Kuma stores all monitor configurations, notification webhooks (Telegram, Discord, Slack, PagerDuty), and heartbeat history inside `/app/data/kuma.db` (SQLite). Before upgrading from `louislam/uptime-kuma:1` to `louislam/uptime-kuma:2`, always create a consistent snapshot of the `uptime_kuma_data` volume.

backup-and-upgrade-kuma.sh
bash
# 1. Create a compressed tar backup of the Uptime Kuma Docker volume
docker run --rm \
  -v uptime_kuma_data:/data:ro \
  -v $(pwd):/backup \
  alpine tar czf /backup/uptime-kuma-backup-$(date +%F).tar.gz -C /data .

# 2. Pull the latest stable image and recreate the container
docker compose pull uptime-kuma
docker compose up -d uptime-kuma

Pre-Deployment Verification Checklist

  • Verify port 3001 is NOT bound to 0.0.0.0 on the host VPS (use internal Docker network or 127.0.0.1:3001:3001).
  • Enable Settings -> Reverse Proxy -> Trust Proxy: Yes inside the Uptime Kuma admin dashboard.
  • Mount /var/run/docker.sock:/var/run/docker.sock:ro if monitoring local Docker containers.
  • Schedule daily backups of /app/data/kuma.db to Cloudflare R2 or off-site storage.
India's First & Only Developer PaaS

Deploy on Vexlo Cloud in 60s (₹149/mo UPI)

Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.

Frequently Asked Questions

Why does Uptime Kuma show 'Cannot connect to the socket server. Reconnecting...' behind a proxy?

Your reverse proxy is stripping the HTTP `Upgrade: websocket` and `Connection: upgrade` headers required by Socket.IO. Add WebSocket upgrade headers in Nginx or route directly through Traefik.

Why is port 3001 accessible from the internet even though UFW is enabled on Ubuntu?

Publishing `ports: - "3001:3001"` in Docker Compose writes rules directly to the Linux kernel `iptables` NAT table before UFW input chains evaluate traffic. Change it to `127.0.0.1:3001:3001` or remove the `ports` block when using a containerized reverse proxy.

How do I monitor other Docker containers in Uptime Kuma without exposing their ports?

Bind `/var/run/docker.sock:/var/run/docker.sock:ro` in Uptime Kuma's volumes, then go to Settings -> Docker Hosts in Uptime Kuma and add `/var/run/docker.sock`.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →