Self-host Uptime Kuma on a managed VPS: monitor your services around the clock

What Uptime Kuma monitors

Uptime Kuma checks your services at regular intervals, as often as every 20 seconds, keeps the history of their responses and alerts you as soon as one stops responding. You use it from a web interface, available in several languages.

• Monitors: HTTP and HTTPS, keyword search in a page, JSON queries, TCP, WebSocket, ping, DNS records, Docker containers, and a "push" monitor for a scheduled task that reports its own run.
• Alerts: more than 90 notification services, including Telegram, Discord, Slack and email.
• Status pages: several public pages, each on its own domain if you wish.
• Certificates: the HTTPS certificate details of each monitored service.
• The account: two-factor authentication, and routing through a proxy for the monitors that need one.

Place Uptime Kuma on a different server from the services it monitors. On a separate machine, it sees the outage from the outside and sends the alert while your services are down.

What the MIT licence allows

Uptime Kuma is published under the MIT licence. It allows you to use, copy, modify, merge, publish, distribute, sublicense and sell the software, on one condition: keep the copyright notice and the licence text in every copy.

You can therefore run Uptime Kuma in your company, monitor your clients’ services with it and open status pages for them, with no licence to buy.

Installing with Docker Compose

Uptime Kuma’s documentation starts with Docker Compose. On a server where Docker is installed, create a folder and fetch the official file:

mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml

The project’s file publishes port 3001 on all of the server’s addresses. Behind a reverse proxy, limit it to the local address, as the README suggests:

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

docker compose up -d

• A port published on 127.0.0.1: by default, Docker publishes on all of the server’s addresses, ahead of the ufw firewall rules. Bound locally, Uptime Kuma can only be reached through the reverse proxy.
• A data folder on a local disk: it holds the kuma.db database, uploaded files and screenshots. The project rules out NFS and other network file systems, because SQLite needs reliable file locks.
• The 2 tag follows Uptime Kuma version 2, and moving to a later major version remains your choice.
• The 2-slim image is lighter, about 185 MB to download against 620 MB: it leaves out Chromium and the embedded MariaDB that the 2 image carries. The 2 image is the one the project recommends, and a "Browser Engine" monitor then needs an external Chromium with 2-slim.

On first launch, open the interface: a wizard has you choose the database, then create the administrator account. Turn on two-factor authentication at your first login.

The project gives no figures for memory or processor: the size depends on how many services you monitor and how often. On a Managed VPS, tell us how you will use it and we recommend the right size.

HTTPS and WebSocket: the reverse proxy

On a public network, the project calls for HTTPS. Uptime Kuma relies on WebSocket: the reverse proxy must pass the Upgrade and Connection headers. It is served at the root of a domain or subdomain, and its wiki rules out subfolders such as example.com/uptimekuma.

With Caddy

Caddy obtains and renews the certificate on its own, and passes WebSocket through with no extra setting:

uptime.example.com {
    reverse_proxy 127.0.0.1:3001
}

With Nginx and Certbot

server {
    listen 80;
    server_name uptime.example.com;

    location / {
        proxy_pass         http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
    }
}

Certbot then installs the Let’s Encrypt certificate and the redirect to HTTPS, and renews the certificate on its own:

sudo certbot --nginx -d uptime.example.com

When Uptime Kuma can only be reached through the proxy, open its settings, "Settings", "Reverse Proxy", "HTTP Headers", and set "Trust Proxy" to "Yes": the logs then show visitors’ real addresses.

SQLite or MariaDB

Since version 2, Uptime Kuma offers three databases, chosen in the first-launch wizard:

To set the choice in advance, without going through the wizard, add the variables UPTIME_KUMA_DB_TYPE, UPTIME_KUMA_DB_HOSTNAME, UPTIME_KUMA_DB_PORT, UPTIME_KUMA_DB_NAME, UPTIME_KUMA_DB_USERNAME and UPTIME_KUMA_DB_PASSWORD to the service in compose.yaml.

Notifications, email included

A monitor is only useful if the alert reaches you. Declare your channels in "Settings", "Notifications", send a test message from each, and set up two, for example a messaging app and email: if one goes down, the other takes over.

For email, Uptime Kuma connects to an SMTP server. On a Simafri VPS, sending goes through an authenticated relay on port 587: the address of a mail account you already have, or Simafri Suite.

Backups and updates

Since version 2, backing up the data folder is the only method the project supports. With SQLite or the embedded MariaDB, everything is in there. A SQLite database copied mid-write can end up corrupted: stop the container for the duration of the copy, knowing that the monitors stop with it.

docker compose stop
tar -czf uptime-kuma-$(date +%F).tar.gz data
docker compose start

Updating

The project’s wiki gives two commands, run from the compose.yaml folder. The data folder stays in place:

docker compose pull
docker compose up -d --force-recreate

Read the release notes before each update: some carry security fixes, like 2.5.9 of October 31, 2026. A backup just beforehand gives you a simple way back.

Moving from version 1 to version 2 takes more care: back up the data folder with the container stopped, and let the migration run to completion, because an interrupted migration means restoring the backup. The project measured about 7 minutes for 20 monitors and 90 days of history, and much more on a modest machine or with more monitors.

Who does what on a Managed VPS

Self-hosting means running the server on top of the application. On a Managed VPS, our teams take the server in hand and proactively monitor your instance; Uptime Kuma remains your software, with its settings and its data.

If you would rather have our teams work inside the application itself, that service is billed hourly or at a fixed price, with a quote given before the work begins.