How to self-host Uptime Kuma with Docker Compose

What is Uptime Kuma?

Uptime Kuma is a self-hosted monitoring tool that checks websites, APIs, ports, DNS records, Docker containers and more, then alerts you when something goes down. It is open source under the MIT license and has a polished real-time dashboard, public status pages and more than 90 notification channels, including email, Slack, Discord, Telegram and ntfy.

Requirements

• Any small Linux server: 1 vCPU and 512 MB of RAM handle hundreds of monitors.
• Docker Engine and Docker Compose v2.
• Local storage for the data folder. The project warns that SQLite on NFS or other network file systems can corrupt the database.

Step 1: Prepare the server

This guide assumes Ubuntu 24.04 with Docker installed. If you need Docker, follow the Docker Engine install guide. Ideally, run Uptime Kuma on a different machine or provider than the services it monitors, so it can still alert you when they fail.

mkdir -p ~/uptime-kuma && cd ~/uptime-kuma

Step 2: Create the Docker Compose file

Uptime Kuma is a single container. Save this as docker-compose.yml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      # Optional: let Kuma monitor containers on this host (read-only socket).
      # - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      TZ: "Europe/London"

The 2 tag follows the latest 2.x release, which is what the official Compose file uses. Uptime Kuma needs no secrets in the Compose file. The admin account is created in the browser.

Think twice before mounting the Docker socket. Even read-only, it exposes details about every container on the host, and anyone who takes over the app could use it. Only add it if you need Docker container monitors.

Step 3: Start and open the app

docker compose up -d

Open http://YOUR_SERVER_IP:3001. Uptime Kuma 2 first asks which database to use. Choose SQLite unless you plan to run a very large number of monitors. Next, create the admin account with a strong password. Then click "Add New Monitor", pick a type (HTTP(s), TCP port, ping, DNS, keyword and more), set the interval, and attach a notification channel under Settings, Notifications.

Step 4: Put it behind HTTPS

Uptime Kuma uses WebSockets for its live dashboard, so the proxy must pass them. Caddy does that automatically:

status.example.com {
    reverse_proxy 127.0.0.1:3001
}

With Nginx Proxy Manager, create a proxy host for port 3001 and enable "Websockets Support". After HTTPS works, change the port mapping to "127.0.0.1:3001:3001" so the dashboard is only reachable through the proxy, and set Settings, Reverse Proxy, "Trust Proxy" to Yes so login logs show real client IPs. Then enable two-factor authentication under Settings, Security.

Backups and upgrades

All state is in the ./data folder: the SQLite database kuma.db, uploaded status-page logos and settings. Stop the container briefly for a consistent copy:

docker compose stop && tar czf kuma-$(date +%F).tgz data && docker compose start

To upgrade within version 2:

docker compose pull && docker compose up -d

If you are coming from Uptime Kuma 1.x, back up data first. The first start on version 2 runs a database migration that can take a long time with a big history, and you should not interrupt it.

Troubleshooting

• Dashboard loads but stays on "Connecting...": the reverse proxy is not forwarding WebSockets. Enable WebSocket support on the proxy host.
• "SQLITE_BUSY" or corruption errors: the data folder is on NFS or a network share. Move it to local disk.
• Monitors for localhost services fail: inside the container, localhost is the container itself. Use the host's LAN IP or the Docker service name on a shared network.
• Notifications never arrive: use the "Test" button on the notification settings page and check docker compose logs uptime-kuma for the provider's error.

Next steps

Create a public status page for your services, add maintenance windows for planned work, set up a second, external check that watches Uptime Kuma itself, and group monitors with tags.