> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arct.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Uptime Kuma on a VPS

> Run Uptime Kuma 2 on an Arct Cloud Linux VPS with Docker, HTTPS, persistent monitoring data, backups, and safe updates.

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

<Steps>
  <Step title="Deploy Ubuntu 24.04">
    [Deploy a server](/compute/virtual-machines/deploy), select an appropriately sized plan, and choose Ubuntu 24.04.
  </Step>

  <Step title="Connect over SSH">
    Find the server IP address in the Arct Cloud console, then connect:

    ```bash theme={null}
    ssh ubuntu@YOUR_SERVER_IP
    ```

    See [Connect via SSH](/compute/virtual-machines/connect-ssh) if you need help with keys or usernames.
  </Step>

  <Step title="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:

    ```bash theme={null}
    getent ahostsv4 status.example.com
    ```
  </Step>

  <Step title="Install Docker Engine">
    Install Docker and the Compose plugin from Docker's official Ubuntu repository:

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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
    ```

    <Warning>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.</Warning>
  </Step>

  <Step title="Start Uptime Kuma and create the administrator privately">
    Start Uptime Kuma while it is still reachable only on server loopback:

    ```bash theme={null}
    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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Configure the public reverse proxy and HTTPS">
    Replace `status.example.com` with your domain. The WebSocket headers are required by Uptime Kuma.

    ```bash theme={null}
    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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Verify the deployment">
    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

1. Read the [release notes](https://github.com/louislam/uptime-kuma/releases), especially migration notes.

2. Stop the service and take a complete data-directory backup as described above.

3. Record the current immutable image digest:

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

4. Pull and recreate the service:

   ```bash theme={null}
   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
   ```

5. 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Official Resources

<CardGroup cols={3}>
  <Card title="Uptime Kuma Installation" icon="book-open" href="https://github.com/louislam/uptime-kuma/wiki/%F0%9F%94%A7-How-to-Install">
    Official Docker, Compose, storage, and reverse-proxy guidance.
  </Card>

  <Card title="Uptime Kuma on GitHub" icon="github" href="https://github.com/louislam/uptime-kuma">
    Source code, security policy, and issue tracker.
  </Card>

  <Card title="Uptime Kuma Releases" icon="tag" href="https://github.com/louislam/uptime-kuma/releases">
    Stable releases, breaking changes, and migration notes.
  </Card>
</CardGroup>

<Note>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.</Note>