How to Build a Simple Uptime Dashboard with Uptime Kuma

Before you begin

• A Linux VPS or home server with Docker and Docker Compose already installed.
• SSH access and permission to create a new application directory.
• At least one site, API, or local service you want to monitor.
• A plan for whether the dashboard stays private behind a VPN or reverse proxy, or becomes internet-facing with authentication.

Uptime monitoring matters because outages often start quietly. A certificate expires, a Docker container crashes, a reverse proxy route breaks, or a database-dependent page starts returning errors while the server itself still answers on port 80. Uptime Kuma gives you a fast way to spot those problems before users have to tell you.

Why this setup is worth doing

Many beginners do not have any monitoring at all. That means the first alert system is usually a customer, a teammate, or your own late-night frustration. Uptime Kuma is a strong first step because it is free, open source, visually clear, and practical enough for small production systems. It can check HTTP endpoints, TCP ports, ping targets, DNS records, SSL expiry, and more without forcing you into a heavyweight observability stack.

Step 1: Deploy Uptime Kuma with Docker Compose

Create a clean directory for the service:

mkdir -p ~/apps/uptime-kuma
cd ~/apps/uptime-kuma

Create a Compose file named compose.yml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - uptime-kuma-data:/app/data

volumes:
  uptime-kuma-data:

Start the container:

docker compose up -d

Check that it is running:

docker compose ps
docker compose logs --tail=50

Open http://YOUR_SERVER_IP:3001 in a browser. On first launch, Uptime Kuma will ask you to create an admin account. Use a strong password, especially if the dashboard will ever be reachable from the public internet.

If you already use Nginx, Caddy, or Traefik, a better production habit is to keep port 3001 private and publish the dashboard through your reverse proxy with HTTPS and access controls.

Step 2: Create your first useful monitors

After logging in, click Add New Monitor. Start with checks that represent real user-facing health, not just server existence.

Example 1: Website homepage

• Type: HTTP(s)
• Friendly Name: Main Website
• URL: https://example.com/
• Heartbeat Interval: 60 seconds
• Retries: 2 or 3

Example 2: API health endpoint

• Type: HTTP(s)
• Friendly Name: API Health
• URL: https://api.example.com/health
• Expected Status Code: 200
• Optional keyword check if your endpoint returns a known success string

Example 3: SSH or database port reachability

• Type: TCP Port
• Friendly Name: SSH Port
• Hostname: server.example.com
• Port: 22

Example 4: SSL expiry warning

• Type: HTTP(s) or keyword monitor with SSL expiry enabled
• Set warning days so you know before a certificate becomes urgent

Good monitoring asks, “What failure would hurt me most?” For a blog, homepage uptime may be enough. For a login app, you may want a monitor against a login page, an API route, and a database-dependent endpoint so a partial outage does not stay invisible.

Step 3: Add alerts and an optional public status page

A dashboard you never open is not real monitoring. Add at least one notification target.

Inside Uptime Kuma, open Settings > Notifications and choose a method such as:

• Email via SMTP
• Telegram
• Discord webhook
• Slack webhook
• Gotify
• Pushover

Send a test notification before trusting it. Then attach that notification channel to each important monitor.

If you want a public-facing status page for customers or teammates, create one under Status Pages, choose which monitors to expose, and give it a clean name. Keep internal-only services off the public page. Public status pages are useful, but they should not leak private hostnames or internal architecture.

# Optional update workflow later
docker compose pull
docker compose up -d

Expected outcomes and how to verify them

When the setup is working properly, you should be able to verify all of the following:

• The container stays up after a reboot because of restart: unless-stopped.
• The dashboard loads consistently in the browser.
• At least one monitor turns green after a successful check.
• A forced failure, such as stopping a test container or pointing a monitor at a bad path, creates an alert.
• Your notification channel receives the alert and recovery message.

Do not stop at the green dashboard. Trigger one controlled failure so you know the alert path works under real conditions.

Troubleshooting common problems

The dashboard does not load on port 3001.
Check whether the container is running and whether the server firewall allows the port.

docker compose ps
docker compose logs --tail=100
sudo ss -tulpn | grep 3001

Monitors show down for internal services.
If Uptime Kuma runs in Docker, localhost inside the container is not your host machine. Use the correct reachable hostname, container network name, or reverse-proxied URL.

Notifications never arrive.
Use the built-in test button first. For SMTP, verify host, port, username, password, and whether the provider requires an app password. For webhook systems, confirm the URL was copied correctly.

Checks are green but users still report problems.
Your monitor may be too shallow. A homepage 200 response does not prove logins, forms, uploads, or database queries still work. Add a better health endpoint or more representative checks.

What to do next

After monitoring, the next maturity step is making deployments safer so fewer alerts happen in the first place. Continue with How to Use rsync for Fast, Safe VPS Deployments.