Install Uptime Kuma on a VPS

Arct Cloud provides an unmanaged Linux VPS. Uptime Kuma is not preinstalled or managed by Arct Cloud; you are responsible for installation, monitor configuration, security, backups, and updates. This guide installs the stable Uptime Kuma 2 major channel on Ubuntu 24.04 using the project’s official Docker Compose method.

Requirements

Basis	CPU and memory	Software and storage
Uptime Kuma requirements	The project does not publish a numeric CPU or RAM minimum	Docker on a major Linux distribution and local storage with POSIX file-lock support for `/app/data`; NFS is not supported
Practical Arct recommendation	2 vCPUs and 4 GB RAM (`cvm.micro`)	40 GB NVMe for a modest number of monitors and retention; increase resources for many monitors, short intervals, or long history

Resource use depends on monitor type, check frequency, retained heartbeats, and notification integrations. Start conservatively and watch memory and disk use after importing your monitors.

Install Uptime Kuma

Deploy Ubuntu 24.04

Deploy a server, select an appropriately sized plan, and choose Ubuntu 24.04.

Connect over SSH

Find the server IP address in the Arct Cloud console, then connect:

ssh ubuntu@YOUR_SERVER_IP

See Connect via SSH if you need help with keys or usernames.

Point a dedicated domain to the server

Uptime Kuma does not support being served from a subdirectory. Create an A record such as status.example.com pointing to the server’s public IPv4 address. Add an AAAA record only when IPv6 is configured. Confirm the record resolves:

getent ahostsv4 status.example.com

Install Docker Engine

Install Docker and the Compose plugin from Docker’s official Ubuntu repository:

sudo apt update
sudo apt install -y 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 >/dev/null <<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 -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run --rm hello-world

Create the Compose project

The official 2 image tag stays on the current stable v2 release line. The local data directory persists the SQLite database, uploaded assets, and application settings. Port 3001 is bound only to loopback.

sudo install -d -m 750 -o "$USER" -g "$USER" /opt/uptime-kuma
cd /opt/uptime-kuma

tee compose.yaml >/dev/null <<'EOF'
services:
  uptime-kuma:
    container_name: uptime-kuma
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "127.0.0.1:3001:3001"
EOF

sudo docker compose config

Keep /opt/uptime-kuma/data on the VPS’s local NVMe filesystem. NFS and other filesystems without reliable POSIX locks can corrupt Uptime Kuma’s SQLite database.

Start Uptime Kuma and create the administrator privately

Start Uptime Kuma while it is still reachable only on server loopback:

cd /opt/uptime-kuma
sudo docker compose up -d

From a second terminal on your local computer, open an SSH tunnel and leave it running:

ssh -N -L 3001:127.0.0.1:3001 ubuntu@YOUR_SERVER_IP

Open http://localhost:3001, create the administrator with a unique password, and enable two-factor authentication in Settings → Security. Leave authentication enabled unless a tested external access-control layer will protect the entire dashboard. Close the tunnel with Ctrl+C after the administrator and two-factor authentication are configured.

Configure the public reverse proxy and HTTPS

Replace status.example.com with your domain. The WebSocket headers are required by Uptime Kuma.

sudo apt install -y nginx certbot python3-certbot-nginx

sudo tee /etc/nginx/sites-available/uptime-kuma >/dev/null <<'EOF'
server {
    listen 80;
    listen [::]:80;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        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;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/uptime-kuma \
  /etc/nginx/sites-enabled/uptime-kuma
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d status.example.com

If UFW is enabled, allow SSH and the reverse proxy:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

After https://status.example.com works, sign in with the secured administrator account. Open Settings → Reverse Proxy → HTTP Headers and enable Trust Proxy so forwarded client addresses are handled correctly.

Verify the deployment

cd /opt/uptime-kuma
sudo docker compose ps
sudo docker inspect uptime-kuma --format '{{.State.Health.Status}}'
curl -I http://127.0.0.1:3001
curl -I https://status.example.com
sudo docker logs --tail 50 uptime-kuma

Add a test HTTP monitor and configure a notification channel. Trigger its Test action before depending on it for alerts.

Ports, Probes, and Secrets

Only ports 80 and 443 need inbound public access. Port 3001 remains on 127.0.0.1. Uptime Kuma normally initiates outbound checks, so a monitor’s destination port must be allowed outbound; you do not need to open that port inbound on the Uptime Kuma server. Monitor URLs, credentials, notification tokens, two-factor settings, and history are stored under /opt/uptime-kuma/data. Protect backups as secrets. Do not mount the Docker socket merely to monitor public endpoints; access to that socket is effectively root access to the host. For email notifications on Arct Cloud, use a provider’s authenticated submission endpoint on port 587. Outbound ports 25 and 465 are blocked by default.

Back Up and Restore

Uptime Kuma 2 removed the old JSON backup and restore feature. The project’s supported backup method is to stop Uptime Kuma and copy its complete data directory. Create a consistent archive:

cd /opt/uptime-kuma
sudo install -d -m 700 /var/backups/uptime-kuma
uptime_backup_stamp=$(date +%F-%H%M%S)
sudo docker compose stop uptime-kuma
sudo stat -c '%u:%g %a %n' data data/kuma.db | sudo tee \
  "/var/backups/uptime-kuma/ownership-${uptime_backup_stamp}.txt" >/dev/null
sudo tar --acls --xattrs -czf \
  "/var/backups/uptime-kuma/data-${uptime_backup_stamp}.tar.gz" data
sudo docker compose start uptime-kuma

Copy the archive and matching ownership file to encrypted storage outside the VPS and test them periodically. To restore, use the same Uptime Kuma major version, stop the service, preserve the current directory, and extract the selected archive with its ACLs, extended attributes, and numeric ownership:

cd /opt/uptime-kuma
sudo docker compose down
sudo mv data "data.before-restore.$(date +%F-%H%M%S)"
sudo tar --acls --xattrs --numeric-owner -xzf /path/to/data-backup.tar.gz
sudo stat -c '%u:%g %a %n' data data/kuma.db

Compare the restored uid:gid and mode with the matching ownership-*.txt file before starting the container. If they match, start and verify Uptime Kuma:

sudo docker compose up -d
sudo docker logs --tail 100 uptime-kuma

The renamed directory makes the restore reversible. Confirm monitors, history, users, and notification settings before removing it.

Update Safely

The 2 tag receives stable v2 updates. Before every update:

Read the release notes, especially migration notes.
Stop the service and take a complete data-directory backup as described above.

Record the current immutable image digest:

sudo docker image inspect louislam/uptime-kuma:2 \
  --format '{{index .RepoDigests 0}}'

Pull and recreate the service:

cd /opt/uptime-kuma
sudo docker compose pull
sudo docker compose up -d --force-recreate
sudo docker compose ps
sudo docker logs --tail 100 uptime-kuma

Verify the dashboard, one monitor, and one notification test before pruning the previous image.

Database migrations can make an in-place downgrade unsafe. For rollback, stop the service, restore the pre-update data archive, and recreate the container with the previously recorded image digest. Never interrupt a documented major-version migration; restore the pre-migration backup if it fails.

Troubleshooting

Nginx returns 502 Bad Gateway

Run sudo docker compose -f /opt/uptime-kuma/compose.yaml ps, inspect sudo docker logs --tail 100 uptime-kuma, and confirm curl -I http://127.0.0.1:3001 succeeds.

The dashboard says it cannot connect to the socket server

Confirm the Nginx configuration includes proxy_http_version 1.1 plus the Upgrade and Connection headers. If a CDN is in front, enable WebSocket support there too.

The container restarts or reports SQLite locking errors

Confirm /opt/uptime-kuma/data is on local storage, not NFS. Check free space with df -h /opt/uptime-kuma and memory with free -h, then inspect the container logs before restarting it.

Email notification tests fail

Use authenticated SMTP submission on port 587, verify DNS resolution and provider credentials, and check whether the provider requires a specific sender address. Ports 25 and 465 are blocked by default on Arct Cloud.

Official Resources

Uptime Kuma Installation

Official Docker, Compose, storage, and reverse-proxy guidance.

Uptime Kuma on GitHub

Source code, security policy, and issue tracker.

Uptime Kuma Releases

Stable releases, breaking changes, and migration notes.

Uptime Kuma is developed by its open-source maintainers. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by the Uptime Kuma project.

Getting Started

Virtual Machines

Migrations

Billing & Payments

Account

Install Uptime Kuma on a VPS

Requirements

Install Uptime Kuma

Ports, Probes, and Secrets

Back Up and Restore

Update Safely

Troubleshooting

Official Resources

Uptime Kuma Installation

Uptime Kuma on GitHub

Uptime Kuma Releases

​Requirements

​Install Uptime Kuma

​Ports, Probes, and Secrets

​Back Up and Restore

​Update Safely

​Troubleshooting

​Official Resources

Uptime Kuma Installation

Uptime Kuma on GitHub

Uptime Kuma Releases

Requirements

Install Uptime Kuma

Ports, Probes, and Secrets

Back Up and Restore

Update Safely

Troubleshooting

Official Resources