Self-hosting Uptime Kuma

You can run your own uptime monitoring with Uptime Kuma on a VPS. The recommended route is Docker with a persistent data volume, then you add monitors for your websites and switch on certificate-expiry alerts and notifications. Be aware that running the monitor on the same server you are testing has blind spots. We explain the workaround.

Before you start

This picks up from a server you can already reach over SSH.

• A Hostworld VPS running AlmaLinux 9 or Ubuntu 24.04. You can start, stop or reboot the VPS in Virtualizor from the Hostworld client area if needed.
• Root or sudo access over SSH.
• Docker available if you follow the recommended method. The Uptime Kuma project recommends Docker. If you prefer a non‑Docker install, Uptime Kuma v2 requires Node.js 20.4 or newer.
• Plan where to store data. Uptime Kuma persists state under /app/data. You must map this to local storage on your VPS. Network file systems are not supported for this directory and can corrupt the database.
• Decide how you will expose the UI. Publishing port 3001 straight to the Internet is risky. A reverse proxy with HTTPS is safer. Uptime Kuma is WebSocket based, so your proxy must pass Upgrade and Connection headers. Mounting Kuma at a subdirectory is not supported. Use a subdomain instead.
• Pick a check interval with care. The project calls out 20 seconds as the practical minimum. The UI warns about performance if you go lower.
• Updating notes. Uptime Kuma v2 images are tagged 2. The deprecated latest tag points to v1. Back up the data directory before major upgrades. If you ever migrate from v1 to v2, do not interrupt the migration.
• IPv6 targets. Docker does not enable IPv6 by default. If you need to monitor IPv6‑only services, you will need an IPv6‑enabled Docker network.
• Scope. Out of the box, checks run from one place: the server where Kuma lives. That means a host or network failure there looks like everything is down. We show options to monitor from elsewhere later.

Step 1: Create a Compose project for Uptime Kuma (recommended)

This creates a working directory for the Compose project and writes a compose.yaml that uses the official v2 image, a local persistent data directory, and port 3001.

AlmaLinux 9 and Ubuntu 24.04

sudo mkdir -p /opt/uptime-kuma
sudo chown -R "$USER":"$USER" /opt/uptime-kuma
cd /opt/uptime-kuma

cat > compose.yaml <<'YAML'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    volumes:
      - ./data:/app/data
    ports:
      - "3001:3001"
    restart: unless-stopped
YAML

What this does:

• Creates /opt/uptime-kuma to hold your Compose files and data.
• Sets ownership to your user so you can edit files there.
• Writes a Compose file using the documented image tag louislam/uptime-kuma:2, maps ./data to /app/data inside the container, publishes port 3001, and makes Docker restart the container unless you stop it.

Do not point ./data at NFS or other network storage. The project warns NFS is not supported and can corrupt the database.

Step 2: Start Uptime Kuma with Docker Compose

This pulls the correct image and starts the service in the background.

AlmaLinux 9 and Ubuntu 24.04

cd /opt/uptime-kuma
docker compose pull
docker compose up -d
docker compose ps

• docker compose pull fetches the latest v2 image for the :2 tag.
• docker compose up -d creates and starts the container detached.
• docker compose ps shows the running state.

Point your browser at http://<your-server-ip>:3001 to reach the UI. If you intend to expose Kuma to the Internet, add a reverse proxy with HTTPS first. If you will proxy it, bind the container to loopback so it is not reachable directly. See the next step.

Step 3: Restrict direct access or put Kuma behind a reverse proxy

This binds port 3001 to 127.0.0.1 if you are using a reverse proxy on the same VPS.

AlmaLinux 9 and Ubuntu 24.04

cd /opt/uptime-kuma
sed -i 's/"3001:3001"/"127.0.0.1:3001:3001"/' compose.yaml
docker compose up -d

• sed changes the port mapping to bind on loopback only.
• docker compose up -d applies the change.

When you add your reverse proxy:

• Forward a subdomain like status.example.com to 127.0.0.1:3001.
• Pass WebSocket Upgrade and Connection headers through. The project wiki includes working nginx, Apache and Caddy examples.
• Do not try to mount Kuma at /monitor under another site. Subdirectory mounting is not supported.

Step 4: Alternative one‑liner with docker run

This starts Kuma as a single container without Compose, mapping a persistent local directory to /app/data, and publishing port 3001.

AlmaLinux 9 and Ubuntu 24.04

mkdir -p ~/uptime-kuma-data
docker run -d --name uptime-kuma \
  -p 3001:3001 \
  -v ~/uptime-kuma-data:/app/data \
  --restart unless-stopped \
  louislam/uptime-kuma:2

• mkdir -p ~/uptime-kuma-data creates a data directory in your home folder.
• docker run pulls the v2 image if needed, starts Kuma detached, maps port 3001, and persists data to your local directory.

To restrict access for a reverse proxy, bind to loopback by changing -p 3001:3001 to -p 127.0.0.1:3001:3001.

Step 5: Add monitors for websites and certificates

This configures HTTP(S) checks and certificate expiry alerts in the UI.

1. Open Kuma in your browser on port 3001. On first load you will be prompted to create an admin account.
2. Select Add New Monitor.
3. Choose the HTTP(s) monitor type for websites.
4. Fill in a name and the full URL to check. Set the heartbeat interval. Keep intervals at or above 20 seconds for reliability.
5. If you use self‑signed certificates or development endpoints, enable Ignore TLS/SSL errors.
6. Switch on Certificate Expiry Notification for this monitor. The number of days’ notice is controlled globally under Settings. You will see certificate details such as Valid To, Days Remaining, Issuer and Fingerprint in the monitor view.
7. Save the monitor. You will see up or down events and certificate info after the first check finishes.

Other useful monitor types include Keyword, JSON Query, WebSocket, Ping, DNS, TCP, Push, Steam game servers and Docker containers. Certificate tracking is part of HTTPS monitors. A /api/badge/<id>/cert-exp badge endpoint is available if you want to display expiry timelines elsewhere.

Note for IPv6‑only targets: Docker does not enable IPv6 by default. If checks to an IPv6‑only host fail from a containerised Kuma, create an IPv6‑enabled Docker network as shown on the project’s troubleshooting page and attach your service to it.

Step 6: Set up notifications

This wires alerts to your preferred channels.

1. Go to Settings → Notifications, then choose Set Up Notification.
2. Pick a provider. Kuma supports 90+ options natively and via Apprise, including chat apps and email. Enter the token, URL or credentials the provider requires.
3. Save the notification profile. Optionally send a test if the provider supports it.
4. Attach the profile to a monitor: edit the monitor, open Notifications, and select the notification you created. Choose which events should alert.

The notification list on the wiki links to each provider’s specific requirements. If a provider uses secrets, Kuma supports _FILE variants of environment variables in Docker for loading them from files.

Step 7: Keep Kuma updated and back it up

This updates Kuma to the latest v2 image and reminds you how to protect your data.

• Back up first. The only directory you need is the data directory you mapped to /app/data. Take a copy before major upgrades or migrations.

AlmaLinux 9 and Ubuntu 24.04

This archives your data directory from the Compose example.

cd /opt/uptime-kuma
tar -czf uptime-kuma-data-backup.tgz data/

Update with Docker Compose:

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

• docker compose pull fetches the newest :2 image. Image builds can take time to appear after a release.
• docker compose up -d recreates the container with the updated image and the same persistent volume.

Update a container started with docker run:

docker pull louislam/uptime-kuma:2
docker stop uptime-kuma
docker rm uptime-kuma
docker run -d --name uptime-kuma \
  -p 3001:3001 \
  -v ~/uptime-kuma-data:/app/data \
  --restart unless-stopped \
  louislam/uptime-kuma:2

If you are upgrading from v1 to v2 in a non‑Docker install, follow the migration guide: back up the data directory, ensure Node.js is 20.4 or newer, and do not interrupt the migration. If something goes wrong, restore from your backup.

Do not use the deprecated latest tag. It points to v1 and will leave you on the old release. Use :2 or :2-slim as documented.

Step 8: Optional — use MariaDB instead of SQLite

This shows how to switch the database backend to MariaDB in v2 with environment variables. New deployments can choose MariaDB. Direct migration of an existing SQLite database to MariaDB is not supported by the project, and third‑party export or import tools are not recommended.

Add environment variables to your Compose service to enable MariaDB:

AlmaLinux 9 and Ubuntu 24.04

cd /opt/uptime-kuma
sed -i '/container_name: uptime-kuma/a \    environment:\n      - UPTIME_KUMA_DB_TYPE=mariadb\n      - UPTIME_KUMA_DB_HOST=127.0.0.1\n      - UPTIME_KUMA_DB_PORT=3306\n      - UPTIME_KUMA_DB_NAME=uptimekuma\n      - UPTIME_KUMA_DB_USERNAME=youruser\n      - UPTIME_KUMA_DB_PASSWORD=yourpass' compose.yaml
docker compose up -d

• Replace the placeholder values with real credentials.
• For secrets, the project supports _FILE variants of these variables to load values from files.

Again, you cannot directly convert an existing SQLite data set to MariaDB in v2. Plan MariaDB from the start if you need it.

Step 9: The obvious flaw — monitoring from one place

By default, Kuma checks from a single location: your VPS. If that host, its network, or its upstream has trouble, every check looks down even if your websites or APIs are fine. There is no native multi‑location quorum feature in Kuma at the time of writing. Users who need multiple vantage points run more than one instance or use external networks for additional checks.

Practical options:

• Run a second Uptime Kuma instance on a different Hostworld VPS and data centre. For example, monitor a site hosted on our London VPS from a Hostworld VPS in New York, or the other way round. That separates the monitoring path from the site’s hosting path.
• Use the Globalping monitor type in v2 to perform a remote check from a single specified location for that monitor. Treat it as one extra vantage point per monitor, not a multi‑location quorum. Combining multiple locations into one monitor is not supported.
• Keep status pages honest. If one Kuma instance says your site is down and the other says it is up, you can avoid false public incidents while you investigate the network path that failed.

If you want help planning this across our UK and US locations, please open a support ticket.

Step 10: Optional features and cautions

• Status pages and badges. Kuma can expose uptime and certificate badges under /api/badge/…. These are useful for public status pages or automation.
• Docker container monitoring. Kuma can monitor containers by accessing the Docker API. The wiki shows two methods: bind‑mount /var/run/docker.sock or expose the Docker daemon over TCP. Both are sensitive. If your Kuma UI is reachable from the Internet, mounting the Docker socket is a severe risk. Only use this in tightly controlled environments.
• Security. Keep authentication enabled in Settings. Prefer a reverse proxy with HTTPS. Bind the container to 127.0.0.1 when proxying.

What next

If you are deciding where to host Kuma, our Linux VPS range gives you UK or US locations to place monitors away from your production servers. If you are already running, you can harden your setup by putting Kuma behind an HTTPS reverse proxy and enabling IPv6 where you need it.

For more server tasks, see our VPS guides. If you need help with your Hostworld VPS, please open a support ticket and we will take a look with you.