Applies to: Uptime Kuma 2.5.9 (Docker image louislam/uptime-kuma:2), Docker Engine 29.9 with Compose 5.7, Ubuntu 24.04 and 26.04, AlmaLinux 9 and 10, nginx 1.30

Install Docker Engine from Docker's own repository, start Uptime Kuma with a small Docker Compose file that keeps its data in a local folder, create the admin account, then put nginx with HTTPS in front of it. Uptime Kuma uses WebSocket, so the proxy must pass the Upgrade and Connection headers or the dashboard will not load.

You need a VPS with root access, about 1 GB of free disk for the image, and a subdomain such as status.example.com pointing to the server. If you would rather not run the server yourself, see managed Uptime Kuma hosting.

1. Install Docker Engine

On Ubuntu 24.04 or 26.04, add Docker's repository and install the packages (commands from Docker's install guide):

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

On AlmaLinux 9 or 10, use Docker's RHEL repository:

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

In our lab both repositories offered docker-ce 29.9.3 and docker-compose-plugin 5.7.0 on all four releases. For more detail, see how to install Docker on a VPS.

2. Create the Compose file

mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma
nano compose.yaml

Paste this file:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "127.0.0.1:3001:3001"
  • ./data:/app/data keeps the database, settings and uploads in /opt/uptime-kuma/data on the server, so they survive updates. The Uptime Kuma README warns that network file systems such as NFS are not supported: keep this folder on a local disk.
  • 127.0.0.1:3001 makes port 3001 reachable only from the server itself. The official file publishes 3001:3001 on every interface. According to Docker, published ports skip the ufw firewall rules, so binding to 127.0.0.1 is the reliable way to keep the port private.
  • The tag: use 2 (latest 2.x) or pin a release such as 2.5.9. Do not use latest: the Uptime Kuma wiki says it is deprecated and still points to version 1.

3. Start it and check the log

docker compose up -d
docker compose logs --tail 20

Lab output (lines trimmed):

Welcome to Uptime Kuma
Your Node.js version: 22.23.4
[SERVER] INFO: Uptime Kuma Version: 2.5.9
[SERVER] INFO: Data Dir: ./data/
[SETUP-DATABASE] INFO: Starting Setup Database
[SETUP-DATABASE] INFO: Waiting for user action...

4. Create the admin account

Port 3001 is closed to the outside, so do the first setup through an SSH tunnel from your own computer:

ssh -L 3001:127.0.0.1:3001 root@your-server-ip

Open http://localhost:3001 in your browser and follow the two screens:

  1. Which database would you like to use? offers Embedded MariaDB, MariaDB/MySQL and SQLite. SQLite is "recommended for small-scale deployments" and needs nothing else. Pick one and press Next; the setup takes a moment.
  2. Create your admin account: enter a Username, Password and Repeat Password, then press Create. You land on the empty dashboard.

Turn on two-factor authentication under Settings, Security, 2FA Settings before you share the address.

5. Put nginx and HTTPS in front

Install nginx (apt install nginx or dnf install nginx) and create /etc/nginx/conf.d/uptime-kuma.conf:

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

    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;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}
sudo nginx -t
sudo systemctl reload nginx

Then add a free certificate with Certbot, which adds the HTTPS server block and the redirect for you (full steps in Nginx HTTPS with Certbot):

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

Uptime Kuma does not work under a sub-folder such as example.com/status; give it its own subdomain. On AlmaLinux, SELinux labels port 3001 as ntop_port_t and only lets nginx connect to it when this boolean is on, otherwise you get a 502 error:

sudo setsebool -P httpd_can_network_connect 1

Finally, in Uptime Kuma open Settings, Reverse Proxy and set Trust Proxy to Yes, so the logs show real visitor IP addresses.

6. Check the WebSocket upgrade

If the page loads but stays blank or keeps reconnecting, the WebSocket headers are missing. Test the proxy from the server:

curl -s -i --http1.1 -m 4 -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" "https://status.example.com/socket.io/?EIO=4&transport=websocket" | head -1

Lab output with the configuration above:

HTTP/1.1 101 Switching Protocols

In the same lab, the same server block without the Upgrade and Connection lines returned HTTP/1.1 400 Bad Request.

7. Update Uptime Kuma

Pull the new image and recreate the container; the data folder stays as it is:

cd /opt/uptime-kuma
docker compose pull
docker compose up -d --force-recreate

Copy the data folder somewhere safe first (stop the container while you copy it). In our lab, removing and recreating the container on the same data volume kept the admin account and every monitor. Going from version 1 to 2 migrates the database: read the wiki's migration guide before that jump.

Next steps: compare server monitoring tools, or run Uptime Kuma on an Uptime Kuma VPS kept apart from the servers it watches, so it still sends alerts when they go down.

Official documentation: Uptime Kuma reverse proxy guide, how to update, Docker on Ubuntu, Docker on RHEL.

Related services

KVM VPS hosting

NVMe SSD and full root access, with Free Basic Managed Support.

Unmanaged dedicated servers

full root access and free IPMI KVM, with Free Basic Managed Support.

Linux server management

hardening, patching, monitoring and automation for Ubuntu, Debian, RHEL and AlmaLinux.

Was this answer helpful?

Still stuck? Open a ticket