EN

Applications

Monitor Your Services with Uptime Kuma

Install Uptime Kuma with Docker Compose on Debian or Ubuntu, protect its access over HTTPS, create your monitors and notifications, then manage updates and backups.

10 min read, updated on 18 November 2026

On this page

Your values

Enter them once and the commands in this guide update.

Uptime Kuma is a self-hosted monitoring tool. It regularly checks your sites, ports and services, keeps a history of their availability and alerts you when something goes down.

By the end of this guide, Uptime Kuma runs in Docker, listens only on the server's local address and answers over HTTPS behind Caddy, with protected access. You have created a first monitor and a notification, and you know how to update and back up the instance.

Order a Server

This guide applies to servers that you administer yourself:

Prerequisites

The docker commands assume that your user belongs to the docker group. Otherwise, add sudo in front of them.

This guide uses version 2.5.12, the latest stable version at the time of writing. Check the current version on the Uptime Kuma releases page. The 3.x branch is still in beta: do not use it in production.

Ports Used

Port Direction Purpose To open
80/tcp Inbound Certificate and redirect to HTTPS, through Caddy Yes
443/tcp Inbound HTTPS access, through Caddy Yes
3001/tcp Local Uptime Kuma interface, on 127.0.0.1 No

The server must also be able to reach, on outbound connections, the monitored services and your notification services.

Step 1: Create the Compose Project

Terminal
sudo mkdir -p /opt/uptime-kuma
sudo chown "$USER": /opt/uptime-kuma
cd /opt/uptime-kuma
nano compose.yaml

Paste this configuration:

YAML
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.12
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data

Start the container:

Terminal
docker compose config --quiet
docker compose up -d
docker compose ps

The container must appear as started (Up). Its health check may stay in the starting state for the first few minutes.

Step 2: Create the Account Through an SSH Tunnel

The first visitor creates the administrator account, so do this before publishing the site. In a terminal on your computer:

Terminal
ssh -N -L 3001:127.0.0.1:3001 YOUR_USER@YOUR_SERVER_IP

The command stays active without printing anything. Then open http://localhost:3001 and:

  1. Choose your language.
  2. Select the SQLite database, suited to a modest installation.
  3. Wait while the database is prepared.
  4. Create the administrator account with a long and unique password.

Step 3: Strengthen the Account

In Settings:

Section Setting Value
Security 2FA Settings Enable two-factor authentication with a TOTP application
Security Disable Auth Do not enable it
Reverse Proxy Trust Proxy Yes, because the service can only be reached through Caddy

Trust Proxy shows the real address of visitors in the logs. Only enable this option if port 3001 stays limited to 127.0.0.1.

Step 4: Publish the Interface with Caddy

Choose the mode that suits your use.

Only your IP address can reach the interface. The /api/push/ URLs stay accessible, so that your scheduled tasks can send their signals. Add this site to /etc/caddy/Caddyfile:

caddyfile
uptime.your-domain.com {
	@push path /api/push/*
	@allowed client_ip YOUR_IP

	handle @push {
		reverse_proxy 127.0.0.1:3001
	}

	handle @allowed {
		reverse_proxy 127.0.0.1:3001
	}

	handle {
		abort
	}
}

If your address changes often, go through WireGuard or Tailscale instead.

Public Access with a Status Page

A status page must stay visible to your users. In this case, the login interface is accessible too, so the two-factor authentication from step 3 becomes essential.

caddyfile
uptime.your-domain.com {
	reverse_proxy 127.0.0.1:3001
}

Apply the Configuration

Caddy passes through the WebSockets that Uptime Kuma needs on its own. Since Caddy is installed on the server and not in Docker, UFW applies to its ports:

Terminal
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

Check the Result

You can close the tunnel with Ctrl+C. Open https://uptime.your-domain.com: the login page must appear with a valid certificate. On the server, check the port:

Terminal
docker ps --filter name=uptime-kuma --format '{{.Names}} {{.Status}} {{.Ports}}'

The output must contain 127.0.0.1:3001->3001/tcp. From another machine, port 3001 must not be open:

Terminal
nmap -Pn -p 3001 YOUR_SERVER_IP

With restricted access, a connection from an address other than yours must be dropped.

Step 5: Add a First Monitor

  1. Click Add New Monitor.
  2. In Monitor Type, choose HTTP(s).
  3. Fill in Friendly Name, then the address to monitor in URL, for example https://www.your-domain.com.
  4. Set Heartbeat Interval (the time between two checks) and Retries (the number of new attempts before the alert).
  5. Enable Certificate Expiry Notification to be warned before the certificate expires.
  6. Click Save.

The most useful monitor types:

Type Use
HTTP(s) Site or API, with a check of the response code
HTTP(s) - Keyword Presence of a word in the page
TCP Port Service listening on a port, such as SSH or a database
Ping Network response from a machine
DNS Resolution of a domain name
Push Scheduled task that reports its own execution

Monitor a Scheduled Task

Create a Push monitor and copy its Push URL. Call it at the end of your script, only if the script succeeds:

Terminal
/usr/local/bin/my-backup.sh && curl -fsS -m 10 --retry 3 "https://uptime.your-domain.com/api/push/YOUR_TOKEN?status=up&msg=OK"

Replace YOUR_TOKEN with the value from your URL. If no signal arrives within the expected time, the monitor switches to the DOWN state. Treat this URL as a secret.

Step 6: Configure Notifications

Open Settings > Notifications, then click Set Up Notification. Uptime Kuma supports many services. The following example uses Telegram:

  1. In Telegram, write to @BotFather, send /newbot and copy the token you receive.
  2. Send a message to your new bot.
  3. In Uptime Kuma, choose Telegram in Notification Type.
  4. Paste the token into Bot Token.
  5. Click Auto Get to fill in Chat ID.
  6. Enable Default enabled to apply it to future monitors, and Apply on all existing monitors for the ones that already exist.
  7. Click Test. If the message arrives, click Save.

For email, choose Email (SMTP) and fill in the settings provided by your email service, preferably with a dedicated account.

A notification only works if it is attached to the monitor. Check this in the Notifications column of each monitor's page.

Create a Status Page

In Status Pages, click New Status Page, choose a name and an address, then add the monitors to display. The page becomes accessible at /status/chosen-name. It is designed to be public and its data is cached for 5 minutes.

With the restricted access from step 4, it will only be visible from your address. To make it public, use the second Caddy block.

Update Uptime Kuma

First back up the data folder and read the release notes. Then replace the tag in compose.yaml and run:

Terminal
cd /opt/uptime-kuma
nano compose.yaml
docker compose pull
docker compose up -d --force-recreate
docker compose ps

Stay on the 2.x branch until you have read the migration guide to version 3. This migration changes the database and cannot be rolled back without a backup.

Back Up and Restore

The data folder is the only item to back up, along with compose.yaml. This is the method supported by the project: the old JSON export was removed in version 2.

Terminal
cd /opt/uptime-kuma
mkdir -p backups
docker compose stop
sudo tar -czf "backups/uptime-kuma-$(date +%F).tar.gz" data compose.yaml
docker compose start
sudo chmod 600 backups/*.tar.gz

The archive contains the database, the accounts and the notification tokens. Copy it off the server to an encrypted location.

To restore an archive, replacing YYYY-MM-DD with its date:

Terminal
cd /opt/uptime-kuma
docker compose down
sudo mv data "data.old-$(date +%F)"
sudo tar -xzf backups/uptime-kuma-YYYY-MM-DD.tar.gz
docker compose up -d

Use the same image version as when the backup was made, or a more recent version from the same branch.

Troubleshooting

Cannot connect to the socket server

The interface cannot open its WebSocket connection. Check that the container is running and look at its logs:

Terminal
docker compose ps
docker compose logs --tail=50 uptime-kuma

If another proxy, such as Cloudflare, sits in front of Caddy, check that WebSockets are enabled there and that the original domain name is passed along.

502 Error with Caddy

Caddy cannot reach the application. Check the local port:

Terminal
curl -I http://127.0.0.1:3001
sudo journalctl -u caddy --no-pager -n 50

A Monitor Shows DOWN While the Service Responds

The check runs from the container, whose network differs from your computer's. Test from the container, adapting the address:

Terminal
docker exec uptime-kuma node -e "fetch('https://www.your-domain.com').then(r => console.log(r.status)).catch(console.error)"

Also check that the monitored service does not block the server's address, for example with a firewall or CrowdSec.

An IPv6 Monitor Fails

By default, the container's Docker network does not use IPv6. If the service can only be reached over IPv6, add a network with IPv6 to compose.yaml:

YAML
services:
  uptime-kuma:
    networks:
      - uptime-kuma-net

networks:
  uptime-kuma-net:
    enable_ipv6: true

Merge these keys with your existing service, then run docker compose up -d again.

Push Signals Do Not Arrive

Test the URL with curl -i from the machine running the task. A dropped connection usually means that the @push block is missing from Caddy. The response must contain "ok":true.

No Notification Arrives

Use the Test button and read the error message. Then check that the notification is enabled on the monitor. For SMTP sending, check the host, port and username with your email service.

Lost Password or Inaccessible Two-Factor Authentication

Run the appropriate command, then follow the instructions displayed:

Terminal
docker exec -it uptime-kuma npm run reset-password
docker exec -it uptime-kuma npm run remove-2fa

database is locked or Corrupted Database

Check that data is on a local disk and not on NFS, and that there is enough disk space with df -h. If the database is damaged, restore your latest backup.

port is already allocated

Another service is using port 3001. Identify it with sudo ss -ltnp | grep ':3001 '. To change the port, modify only the left part, for example 127.0.0.1:3002:3001, then adapt Caddy.

References