How to Install Uptime Kuma on a VPS with Docker Compose

Uptime Kuma is an open-source monitoring dashboard for websites, APIs, servers, DNS and network services. It performs checks on a schedule, records response times, sends notifications when a check fails and can publish a status page for customers or teammates. For a small business, community project or self-hosted stack, it covers the practical gap between having no monitoring and operating a much larger Prometheus or commercial observability platform.

This guide uses Docker Compose because it keeps the deployment repeatable and makes upgrades straightforward. The result is a private dashboard behind HTTPS, with persistent data, tested alerts and monitors that represent real user journeys rather than a collection of meaningless green dots.

What Uptime Kuma Is Good At

Uptime Kuma focuses on availability and response time. It can tell you whether a web page returns the expected status, whether a TCP port accepts connections, whether DNS resolves correctly or whether a server answers ICMP ping. It can also monitor Docker containers, certificates, databases and push-based jobs depending on the chosen monitor type.

It is not a replacement for logs, system metrics or distributed tracing. Pair it with application logs and tools such as Netdata, Prometheus or Grafana when you need to understand why a service is slow or failing. Uptime Kuma answers the first operational question: can a user reach it right now?

Choose the VPS and Monitoring Location

Uptime Kuma is modest for a small monitor set. A practical starting point is 1-2 vCPU, 1-2 GB RAM and 10-20 GB of SSD storage. Increase memory and storage when you retain long histories, use browser-based checks or monitor hundreds of endpoints. HYEHOST Cloud VPS includes IPv4 and IPv6, SSD storage, DDoS protection and snapshots.

• Keep it independent: place the monitor outside the application host or cluster it watches.
• Monitor both address families: create separate IPv4 and IPv6 checks where dual-stack availability matters.
• Use a stable hostname: give the dashboard a dedicated name such as uptime.example.com.
• Plan notification redundancy: do not rely only on an email service hosted on the infrastructure being monitored.

Patch the server and install Docker Engine plus the Compose plugin. Our Docker on Ubuntu guide covers the official repository and validation steps.

sudo apt update
sudo apt full-upgrade -y
docker version
docker compose version

Install Uptime Kuma with Docker Compose

Create a dedicated project directory and Compose file:

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

Add this configuration:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - uptime-kuma-data:/app/data

volumes:
  uptime-kuma-data:

Binding port 3001 to 127.0.0.1 keeps the dashboard off the public interface. The reverse proxy will be the only public entry point. Start the container and check its logs:

docker compose up -d
docker compose ps
docker compose logs --tail=100 uptime-kuma

Before adding a reverse proxy, verify the service locally:

curl -I http://127.0.0.1:3001

Put Uptime Kuma Behind HTTPS

Use Caddy, Nginx or Traefik to terminate TLS and proxy requests to 127.0.0.1:3001. If you have not selected one yet, our reverse proxy comparison explains the trade-offs.

A minimal Caddy configuration is:

uptime.example.com {
    reverse_proxy 127.0.0.1:3001
}

Point the hostname's A and AAAA records to the monitoring VPS, allow inbound TCP ports 80 and 443, then reload Caddy. Create the Uptime Kuma administrator account over the HTTPS hostname and use a unique password.

Create Monitors That Reflect Real Failures

Start with a small set of checks that map to important services. A home page returning HTTP 200 is useful, but it does not prove that login, database access or a background worker is healthy. Add dedicated health endpoints where possible and validate expected content rather than accepting any response.

1. Create an HTTP(s) keyword monitor for the public website and check for a stable phrase.
2. Add an API health endpoint monitor that returns failure when its database or required dependency is unavailable.
3. Create separate ping or TCP monitors for critical servers and network services.
4. Use a push monitor for backups, certificate jobs and scheduled imports.
5. Group related checks by service or location so incidents are easy to read.

A 60-second interval is sensible for most public services. Very short intervals create noise, use more resources and can resemble abusive traffic. Increase retries before declaring a service down when a single dropped packet should not trigger an incident. For a public web application, two or three failed checks are often a better signal than one.

Configure and Test Notifications

A monitor that never reaches a human is only a dashboard. Uptime Kuma supports numerous notification routes, including email, webhooks and chat platforms. Pick at least one channel that remains available if the monitored infrastructure fails.

• Send critical service alerts to an immediate channel.
• Route low-priority lab monitors to a quieter destination.
• Include the monitor name, location and useful response detail.
• Use maintenance windows during planned work rather than ignoring alerts.
• Send a test notification before relying on the integration.

After configuration, stop a harmless test service and confirm the entire chain: failure detection, notification delivery, recovery detection and recovery message. This is the monitoring equivalent of testing a backup restore.

Build a Useful Public Status Page

A status page should help users understand scope without exposing private hostnames or internal addresses. Group monitors into customer-facing services such as Panel, Cloud VPS, DNS and Network. Use clear names, add a custom domain, and show only checks that communicate service health.

Keep internal dependency monitors private. A database hostname, management port or router address rarely belongs on a public page. During an incident, add a short human update rather than expecting customers to interpret raw latency graphs.

Harden the Monitoring Server

• Keep Ubuntu, Docker and Uptime Kuma updated.
• Use SSH keys, disable password authentication and restrict administrative access.
• Expose only SSH, HTTP and HTTPS as required.
• Protect the dashboard account with a unique password.
• Do not place secrets in public monitor names, URLs or status pages.
• Review notification webhooks and tokens when team access changes.

Monitoring URLs can contain API keys or authentication data. Prefer a purpose-built health endpoint with limited access rather than embedding a powerful production credential in the monitor configuration.

Back Up Uptime Kuma and Update Safely

The named volume contains monitor configuration, users, notifications, status pages and history. A VPS snapshot is useful before an update, but keep a separate application backup as well.

cd /opt/uptime-kuma
docker compose stop
docker run --rm \
  -v uptime-kuma_uptime-kuma-data:/source:ro \
  -v /srv/backups:/backup \
  alpine tar -czf /backup/uptime-kuma-$(date +%F).tar.gz -C /source .
docker compose start

Confirm the actual Docker volume name with docker volume ls before running the backup. Copy the archive away from the monitoring VPS and periodically restore it into a disposable deployment.

To update, take a backup, pull the current image and recreate the container:

cd /opt/uptime-kuma
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 uptime-kuma

Open the dashboard, verify several monitors, test one notification and check the public status page. Read the release notes before major-version upgrades because configuration or database migrations can change.

Common Uptime Kuma Problems

Uptime Kuma VPS FAQ

How much RAM does Uptime Kuma need?

A small deployment can run with about 1 GB RAM, but 2 GB gives the operating system, Docker and monitoring history more room. Browser checks and large monitor counts need additional resources.

Can Uptime Kuma monitor IPv6?

Yes. The monitoring VPS must have working IPv6 connectivity, and the target must publish a reachable AAAA record or address. Use separate IPv4 and IPv6 monitors when each path matters.

Should Uptime Kuma run on the same VPS as my website?

It can, but it is a poor failure detector for host-level or network outages because the monitor disappears with the site. A separate VPS or location gives more useful external visibility.

Does Uptime Kuma replace Prometheus or Grafana?

No. Uptime Kuma is strong at availability checks, notifications and status pages. Prometheus and Grafana are better suited to detailed system and application metrics. Many operators use both.

Can I expose an Uptime Kuma status page without exposing the dashboard?

Yes. Publish only the selected status page and keep administrative access protected. Avoid placing internal addresses, credentials or sensitive monitor details on public pages.

Is Uptime Kuma free?

Uptime Kuma is open-source software. You provide the server, domain, backups and operational maintenance.

Make Monitoring Independent and Actionable

A useful Uptime Kuma deployment is not measured by the number of monitors. It is measured by whether it detects a real failure, reaches the right person and helps them understand which service is affected. Keep the monitor outside the systems it watches, validate meaningful health endpoints, test every notification path and back up the configuration.

Deploy it on a HYEHOST Cloud VPS for an independent monitoring point, or review our broader guide to VPS uptime and log monitoring before designing a larger observability stack.

Official Resources

• Uptime Kuma source repository
• Official installation guide
• Uptime Kuma releases
• Docker packet filtering and firewall behaviour
• HYEHOST Docker installation guide