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.
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
- A server running Debian 12 or 13, or Ubuntu 22.04 or 24.04
- SSH access with a user that has
sudo - Docker Engine and Docker Compose, installed with the guide Install Docker Engine and Docker Compose
- Caddy, installed with the guide Caddy as a Reverse Proxy with Automatic HTTPS
- An A record for
uptime.your-domain.compointing toYOUR_SERVER_IP - A local disk for the data: network shares such as NFS are not supported
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
sudo mkdir -p /opt/uptime-kuma
sudo chown "$USER": /opt/uptime-kuma
cd /opt/uptime-kuma
nano compose.yamlPaste this configuration:
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/dataStart the container:
docker compose config --quiet
docker compose up -d
docker compose psThe 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:
ssh -N -L 3001:127.0.0.1:3001 YOUR_USER@YOUR_SERVER_IPThe command stays active without printing anything. Then open http://localhost:3001 and:
- Choose your language.
- Select the SQLite database, suited to a modest installation.
- Wait while the database is prepared.
- 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.
Access Restricted to Your Address (Recommended)
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:
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.
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:
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyCheck 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:
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:
nmap -Pn -p 3001 YOUR_SERVER_IPWith restricted access, a connection from an address other than yours must be dropped.
Step 5: Add a First Monitor
- Click Add New Monitor.
- In Monitor Type, choose HTTP(s).
- Fill in Friendly Name, then the address to monitor in URL, for example
https://www.your-domain.com. - Set Heartbeat Interval (the time between two checks) and Retries (the number of new attempts before the alert).
- Enable Certificate Expiry Notification to be warned before the certificate expires.
- 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:
/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:
- In Telegram, write to @BotFather, send
/newbotand copy the token you receive. - Send a message to your new bot.
- In Uptime Kuma, choose Telegram in Notification Type.
- Paste the token into Bot Token.
- Click Auto Get to fill in Chat ID.
- Enable Default enabled to apply it to future monitors, and Apply on all existing monitors for the ones that already exist.
- 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:
cd /opt/uptime-kuma
nano compose.yaml
docker compose pull
docker compose up -d --force-recreate
docker compose psStay 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.
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.gzThe 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:
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 -dUse 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:
docker compose ps
docker compose logs --tail=50 uptime-kumaIf 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:
curl -I http://127.0.0.1:3001
sudo journalctl -u caddy --no-pager -n 50A 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:
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:
services:
uptime-kuma:
networks:
- uptime-kuma-net
networks:
uptime-kuma-net:
enable_ipv6: trueMerge 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:
docker exec -it uptime-kuma npm run reset-password
docker exec -it uptime-kuma npm run remove-2fadatabase 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.