How to Self-Host Uptime Kuma on a VPS with Docker (2026 Guide)

What is Uptime Kuma and why self-host it

Uptime Kuma is a self-hosted monitoring tool with a reactive web UI. It checks HTTP(s) endpoints, TCP ports, HTTP(s) keyword and JSON query responses, WebSockets, ping, DNS records, push heartbeats, Steam game servers and Docker containers. Checks run on a 20-second interval by default, and you can wire alerts into Telegram, Discord, Gotify, Slack, Pushover, SMTP email and a long list of other notification services.

Self-hosting it means your uptime history, monitor definitions and notification credentials stay on hardware you control. You also get multiple status pages that can be mapped to specific domains, ping charts, TLS certificate info, proxy support and 2FA on the login. The project does not publish a memory requirement, so size the VPS against how many monitors you plan to run rather than a documented figure.

Prerequisites and server setup

You need a Linux VPS with a public IP, Docker Engine and the Docker Compose plugin installed. Confirm both are present:

docker --version
docker compose version

Open port 3001 in your firewall if you want to reach the UI directly before adding a reverse proxy, and open 80/443 for the proxy later. Uptime Kuma stores its SQLite database and uploaded assets under /app/data inside the container, so that path must be backed by a persistent volume.

One important constraint from the README: NFS (Network File System) mounts are not supported. Map /app/data to a local directory or a Docker-managed volume, not to a network share.

Step-by-step installation with Docker

The README ships a compose.yaml you can download directly, but the equivalent minimal configuration below is what you want on a fresh VPS. It pins the 2 image tag used in the official docker run example, publishes port 3001, and keeps data in a named volume.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"
    volumes:
      - uptime-kuma:/app/data

volumes:
  uptime-kuma:

Save that as compose.yaml in a directory such as ~/uptime-kuma, then start it:

mkdir -p ~/uptime-kuma
cd ~/uptime-kuma
# write compose.yaml here
docker compose up -d

Check that the container came up cleanly:

docker compose ps
docker compose logs -f uptime-kuma

Uptime Kuma does not require any environment variables to boot. The README documents no env vars for the Docker image, so there is no .env file to create for a basic install. If you prefer to bind-mount a host directory instead of a named volume, replace the volume line with something like - ./data:/app/data — just keep it on local disk, not NFS.

If you want the container reachable only from the host (for example, behind a proxy on the same machine), change the port mapping to 127.0.0.1:3001:3001 as shown in the README’s localhost-only example.

Accessing the dashboard and reverse proxy

Once the container is running, open http://your-server-ip:3001. On first load you are asked to create an admin username and password. After that, add monitors from the dashboard, configure notifications under Settings, and build status pages.

For anything beyond a quick test, put HTTPS in front of it. With Caddy on the same host, a Caddyfile entry is enough:

status.example.com {
    reverse_proxy 127.0.0.1:3001
}

If you use Nginx Proxy Manager instead, create a proxy host pointing at the container’s host IP and port 3001, enable WebSockets support (Uptime Kuma’s UI uses WebSocket for live updates), and request a Let’s Encrypt certificate from the SSL tab. The README points to the wiki’s installation page for reverse-proxy specifics, so check there if your setup needs extra headers.

Wrapping up

Uptime Kuma gives you a full monitoring stack — checks, notifications, status pages and 2FA — in a single container with one persistent volume. The source, release notes and update instructions live at github.com/louislam/uptime-kuma.

Measured in our sandbox run: peak memory 145.0 MB across 1 container at idle; published port(s) 3001; HTTP probe returned 200. The run took 7.7s with the image already cached; a fresh server also has to download it.

Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.