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/dataon 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:3001on 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 as2.5.9. Do not uselatest: 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:
- 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.
- 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.