Uptime Kuma

Overview

Uptime Kuma watches things and tells you when they stop working. It checks HTTP(S) endpoints, TCP ports, DNS records, ping, and TLS certificate expiry, then sends a notification through Telegram, email, a webhook, or any of the ninety-odd other providers it ships with.

It suits a home server, a side project, or internal infrastructure — anywhere you want to know about an outage before someone else reports it. A small instance needs no separate database: everything lives in one local Docker volume. Public status pages and a container healthcheck are built in, and the interface is translated into more than forty languages.

This recipe deliberately leaves the Docker socket unmounted. Monitoring websites and ports does not need it, and handing a container direct socket access hands it the host.

Security assessment

The recipe runs without privileged, without host networking, and without the Docker socket. It sets no-new-privileges and publishes its port on 127.0.0.1 only, so anything public goes through an HTTPS reverse proxy.

One risk appears only if you later add Docker API access to monitor containers. Put a restricted socket proxy in front of it rather than mounting /var/run/docker.sock into the container: read access to the socket is equivalent to root on the host.

Step-by-step guide

1. Check the server

You need Ubuntu 22.04+ or Debian 12+ with Docker Engine and Docker Compose v2.24+. Budget 1 CPU, 512 MB of RAM, and 2 GB of local disk; 1 GB of RAM is more comfortable. There is no separate database to plan for.

Keep the data on a local filesystem or a Docker volume. Upstream advises against NFS, and SQLite over NFS corrupts in ways that only show up later.

docker --version
docker compose version

2. Prepare the files and variables

Put compose.yaml, .env.example, backup.sh, restore.sh, and proxy/ in a directory of their own:

mkdir -p ~/services/uptime-kuma
cd ~/services/uptime-kuma
cp .env.example .env
chmod 600 .env

.env holds four values: the pinned UPTIME_KUMA_VERSION, the local UPTIME_KUMA_PORT, the UPTIME_KUMA_DATA_VOLUME name, and TZ.

3. Start the container on a VPS

docker compose pull
docker compose up -d
docker compose ps

The image carries its own healthcheck. On a first run the container can sit in starting for a couple of minutes while it lays out the database — that is normal. The port is bound to 127.0.0.1, so nothing is reachable from outside yet.

4. Finish the setup over SSH

ssh -L 3001:127.0.0.1:3001 user@server.example

Open http://localhost:3001, create the administrator, and put the password in a password manager. There is no recovery flow if you lose it.

Local network

Without a reverse proxy, keep the localhost bind and reach the interface through an SSH tunnel. If you trust the LAN, replace 127.0.0.1 in compose.yaml with the server’s own LAN address — 192.168.1.10, say — never 0.0.0.0, and block port 3001 on the external interface with a firewall.

Domain and HTTPS

For a reverse proxy on the host, proxy/Caddyfile, proxy/nginx.conf, and proxy/traefik.yaml are ready to use. Replace status.example.com with your domain. Caddy gets a certificate on its own, the Nginx example expects one from Certbot, and Traefik uses the letsencrypt resolver.

Two things matter here. Turn on Trust Proxy in Uptime Kuma, or every check will be attributed to the proxy’s address. And keep the WebSocket upgrade: all three examples forward it already, and without it the dashboard loads once and then stops updating. For Traefik in a container, replace 127.0.0.1 with a host gateway address that container can actually reach.

Backup

Everything lives in the uptime-kuma-data volume:

chmod +x backup.sh restore.sh
./backup.sh

The script stops the container, writes an archive into ./backups, and starts it again. It stops the container on purpose: copying a live SQLite database gives you an archive that restores into a corrupt one. Keep a second copy off this server.

Restore

Restoring replaces the volume contents with the archive you name:

./restore.sh ./backups/uptime-kuma-YYYYMMDDTHHMMSSZ.tar.gz
docker compose ps

The script takes a safety copy of the current data first, so a restore from the wrong archive is recoverable.

Update

Back up, read the release notes, change UPTIME_KUMA_VERSION in .env, then:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 uptime-kuma

Rollback

Put the previous UPTIME_KUMA_VERSION back in .env and run docker compose pull && docker compose up -d.

If the new release migrated the database, the old image will not read the new schema: return to the old version first, then restore the pre-update archive with restore.sh. Read the upstream release notes before crossing a major version in either direction.

Complete removal

docker compose down stops everything and keeps the data. To remove the container and the data for good:

docker compose down
docker volume rm uptime-kuma-data
rm -rf ~/services/uptime-kuma

Sources: official installation and update guide.

Troubleshooting

The container never turns healthy

Look at the status and the last messages:

docker compose ps
docker compose logs --tail=200 uptime-kuma

A first start takes a while: the container prepares the database before it answers. If it stays unhealthy after that, check free disk space and that the volume is writable — a read-only mount fails quietly here.

The page loads, then stops updating

Uptime Kuma pushes state over a WebSocket. If the dashboard renders once and then freezes, the reverse proxy is dropping the upgrade: check that it forwards the Upgrade and Connection headers. Caddy does this on its own; Nginx and Traefik need it configured, and the examples in proxy/ already do.

Port 3001 is taken

Change UPTIME_KUMA_PORT in .env — to 3101, for instance — and recreate the container:

docker compose up -d

If a reverse proxy on the host points at the old port, update its upstream too.

An update left you with an empty instance

You are almost certainly on a different volume, not on lost data. Check which one the container actually mounts:

docker volume inspect uptime-kuma-data
docker compose config

Do not create a new administrator and do not delete the old volume until you have confirmed the data path and that a backup exists. Creating the administrator again is what makes the empty instance permanent.