How to Deploy Uptime Kuma on a VPS

#Prepare the server

This guide assumes Docker Engine and the Compose plugin are installed, along with a non-root deploy user and a ufw firewall. If not, work through Docker & Compose on Ubuntu first.

Open only SSH and the reverse proxy ports — Uptime Kuma's own port stays internal:

copysudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw enable
sudo ufw status verbose

Outbound traffic matters more than inbound here: the monitor needs to reach what it checks. If your provider has an egress firewall, make sure ICMP is permitted for ping monitors — otherwise every ping check reports down while HTTP checks pass, which is a confusing first hour.

#Install Uptime Kuma

One service, one named volume mounted at /app/data. That volume holds the database, the settings, the notification configuration, and the uploaded status page assets — it is the entire application state.

copymkdir ~/uptime-kuma && cd ~/uptime-kuma

copy# docker-compose.yml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - uptime-kuma:/app/data
    ports:
      # Loopback only — the reverse proxy is the sole public door.
      - "127.0.0.1:3001:3001"

volumes:
  uptime-kuma:

Start it:

copydocker compose up -d
docker compose logs -f

One storage caveat from upstream that bites people on fancier setups: keep that volume on local disk. Network filesystems such as NFS are not supported, and the embedded database misbehaves on them. A plain Docker volume or a local bind mount is what you want.

#HTTPS + domain

Point an A record for status.example.com at the server's public IP and wait for it to resolve, then terminate TLS in front of 127.0.0.1:3001. The simplest path is Automatic HTTPS with Caddy:

status.example.com {
    reverse_proxy 127.0.0.1:3001
}

The one requirement worth naming: Uptime Kuma's dashboard runs over WebSockets. The live-updating monitor list is a socket connection, not polling. Caddy proxies WebSockets transparently, so the block above is complete. On nginx you must forward the upgrade headers, or the page loads and then sits there empty:

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;
}

If you run Caddy as a container, 127.0.0.1 is the proxy's own loopback — put both services in one compose file and use reverse_proxy uptime-kuma:3001 instead, dropping the host port publish.

#First login and hardening

Load https://status.example.com. On a fresh install, the first screen is a setup form that creates the administrator account — there is no default password, and once that account exists the form is gone. There's no open registration to disable, which is a nice property; the only accounts are ones an admin makes.

Do these in order:

1. Use a strong, unique password. This dashboard knows your entire infrastructure map — every hostname, port, and internal endpoint you monitor.
2. Turn on two-factor auth under Profile → Security.
3. Decide what the status page exposes. Status pages are public by design. Give them friendly service names, not internal hostnames, and don't publish one at all if the service list itself is sensitive.
4. Keep the container off the public interface — the 127.0.0.1 bind above is what makes the reverse proxy the only route in.

#Set up monitors and notifications

An uptime monitor that can't reach you is a dashboard, not an alert. Configure notifications before the monitors, so the first real failure pages you.

Notifications live under Settings → Notifications. Pick at least two independent channels, because the useful failure mode is the one where your main channel is also broken:

• A chat webhook (Slack, Discord, Mattermost, Telegram) for day-to-day visibility.
• A push or SMS channel for anything that must wake you up.
• Email/SMTP as a durable record — but never as the only channel, since a mail outage takes your alerts with it.

Mark a notification as the default so new monitors inherit it, and use each channel's Test button — a misconfigured webhook fails silently otherwise.

Monitors. Add more than "the port is open":

• HTTP(s) against a real health endpoint, with keyword matching so a 200-with-an-error-page still counts as down.
• TCP port for databases and services with no HTTP surface.
• Ping for raw host reachability, to separate "the box is gone" from "the app crashed".
• TLS certificate expiry — the built-in certificate check on your HTTPS monitors catches the renewal that quietly stopped working.
• Push monitors for cron jobs and backups: the job calls a URL when it succeeds, and Uptime Kuma alerts when the call doesn't arrive. This is how you find out a nightly backup has been failing for a week.

Set retries and a heartbeat interval that match reality — one missed check on a sixty-second interval is usually noise, three in a row is an incident.

#Backups

Everything is in the one volume, which makes this the easiest backup on the site:

copydocker compose stop
docker run --rm -v uptime-kuma_uptime-kuma:/data -v $(pwd):/backup alpine \
  tar czf /backup/uptime-kuma-$(date +%F).tar.gz -C /data .
docker compose start

Stopping the container first gives a consistent copy of the embedded database — this app is light enough that a few seconds of downtime costs nothing. (The volume's real name is prefixed with the compose project directory; confirm it with docker volume ls if the command above can't find it.)

Copy the archive off the box. And note the irony worth planning around: this server is the thing that tells you other servers died, so it needs its own recovery story. A restore is tar xzf into a fresh volume and docker compose up -d — monitors, history, and notification settings all come back.

#Upgrades

copycd ~/uptime-kuma
docker compose pull
docker compose up -d

The major-version tag keeps you on the current line and applies schema migrations at startup. Back up first — migrations are one-way. Across a major version, read the project's release notes before pulling, since a major bump can change how the database is stored.

#Troubleshooting

Dashboard loads but nothing updates / monitors show as blank. The reverse proxy isn't forwarding WebSockets. Add the upgrade headers (nginx) or use the Caddy block above. Browser dev tools show the failing socket connection immediately.

Every ping monitor is down, HTTP monitors are fine. ICMP is blocked — either by the provider's network firewall or by ufw on the host. Either allow ICMP outbound or switch those checks to TCP port monitors.

A monitor reports down but the site works from your laptop. You're testing from a different network. Check from the monitor's own box: docker compose exec uptime-kuma curl -sI https://example.com. Common causes are DNS resolving differently on the VPS, an IPv6-only AAAA record the server can't reach, or the target's firewall blocking the monitor's IP.

Notifications never arrive. Use the Test button on the notification itself rather than waiting for an outage. Webhook URLs expire and get rotated; SMTP providers reject unauthenticated relays. Also confirm the notification is actually attached to the monitor — a default set after the monitor was created does not apply retroactively.

False alarms every few minutes. The interval is too aggressive or retries are set to 1. Raise retries to 2–3 and lengthen the interval; a monitor that cries wolf gets muted, and a muted monitor is worse than none.

#Verification + next steps

You're done when you can: load https://status.example.com over a valid certificate, log in with 2FA, see a monitor go green, deliberately break something (stop a container, block a port) and receive the alert on a real device, then watch it recover. Until you have seen an alert arrive, you have a dashboard, not monitoring.

From there: publish a status page for the services your users care about, add a push monitor to every backup and cron job you own, and pair it with a metrics stack when you want graphs rather than up/down — Deploy Grafana on a VPS covers that side, and Grafana vs Netdata explains how the two fit together. For the ranked host picks, see Best VPS for Monitoring & Uptime.