Install Uptime Kuma for Uptime Monitoring

Uptime Kuma is a self-hosted monitoring tool that checks whether your websites, servers, and services are up, then alerts you when they are not. It ships as a single Node.js application with a clean real-time dashboard, and the easiest way to run it is inside Docker. This guide walks through a Docker-based install, wiring up your first monitors, configuring alert notifications, and publishing a public status page.

Prerequisites

• A Linux server with Docker and Docker Compose installed (Docker Engine 20.10+ recommended)
• A non-root user with sudo access
• Port 3001 reachable from your browser, or a reverse proxy in front

Install Uptime Kuma with Docker Compose

Using a Compose file gives you easy upgrades and restart policies without typing long docker run arguments every time.

Create the project directory and Compose file

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

cat > docker-compose.yml <<'EOF'
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:
EOF

The named volume uptime-kuma-data keeps your database, certificates, and config outside the container so they survive image upgrades.

Start the container

docker compose up -d

Docker pulls the image on first run. Check the container is running:

docker compose ps

You should see uptime-kuma with status Up. Give it about 10 seconds to initialise, then open http://your-server-ip:3001 in a browser.

Create your admin account

On first visit Uptime Kuma presents a registration screen. Enter a username and a strong password. This creates the only administrator account — there is no default credential to rotate.

Add Monitors

A monitor is a recurring check against a target. Click Add New Monitor in the left sidebar.

HTTP(S) website check

1. Set Monitor Type to HTTP(S).
2. Give it a friendly name, e.g. My Blog.
3. Enter the full URL including the scheme: https://example.com.
4. Set Heartbeat Interval — 60 seconds is a sensible default for most sites.
5. Leave Accepted Status Codes at 200-299 unless your app returns a non-standard success code.
6. Click Save.

TCP port check

Use TCP Port to verify a service is listening even when it has no HTTP interface. Set the hostname and port (e.g. db.internal / 5432 for PostgreSQL). Uptime Kuma will mark it down if the TCP handshake fails within the timeout.

Ping monitor

The Ping type sends ICMP echo requests. Useful for bare-metal hosts or network devices. The container runs as a non-root user by default, so ICMP uses unprivileged sockets — this works on modern kernels without any extra capability.

DNS and keyword monitors

DNS checks that a record resolves to an expected value, handy for detecting misconfigured or hijacked DNS. HTTP(S) — Keyword is an HTTP check that also scans the response body for a string you specify; useful for confirming a page loaded its expected content rather than an error page that still returns HTTP 200.

Configure Notifications

Notifications are defined globally and then attached to individual monitors. Go to Settings → Notifications → Setup Notification.

Email via SMTP

1. Choose Email (SMTP) from the type dropdown.
2. Fill in your SMTP host, port (587 with STARTTLS is standard), username, and password.
3. Set the To field to the address that should receive alerts.
4. Click Test — Uptime Kuma sends a test message immediately.
5. Save, then open a monitor and add this notification in its Notifications tab.

Telegram

1. Create a bot via BotFather and copy the token.
2. Send any message to the bot, then retrieve your Chat ID from https://api.telegram.org/bot<TOKEN>/getUpdates.
3. In Uptime Kuma choose Telegram, paste both values, and test.

Other providers

Uptime Kuma ships with over 90 notification integrations including Slack, PagerDuty, Discord, Gotify, ntfy, Matrix, and webhook. The configuration pattern is the same: fill in the provider-specific credentials, test, save, attach to monitors.

Build a Public Status Page

A status page lets you communicate outages to users without them needing access to the dashboard. Click Status Pages → New Status Page.

1. Choose a URL slug, e.g. status — the page will be served at http://your-server:3001/status/status.
2. Set a title and optional logo.
3. Under Monitors, click Add Group and then drag monitors into the group. You control which monitors are visible publicly.
4. Enable Show Powered By if you wish; disable it for a white-label look.
5. Save and visit the slug URL to confirm it renders correctly.

If you place Uptime Kuma behind a reverse proxy (nginx, Caddy, Traefik), point your status subdomain — e.g. status.example.com — at port 3001 and the slug path becomes optional.

Put Uptime Kuma Behind a Reverse Proxy (Optional but Recommended)

Exposing port 3001 directly is fine for internal use. For public access, terminate TLS at a reverse proxy. A minimal Caddy snippet:

status.example.com {
    reverse_proxy localhost:3001
}

For nginx, set proxy_pass http://127.0.0.1:3001; and include proxy_http_version 1.1; plus the standard WebSocket upgrade headers — Uptime Kuma uses Socket.IO for its live dashboard.

Upgrade Uptime Kuma

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

The named volume preserves your data across image replacements. Check the GitHub releases page for breaking changes before pulling a new major version.

Verification

After setup, confirm everything is working end-to-end:

# Container is running and healthy
docker inspect --format='{{.State.Status}}' uptime-kuma

# Dashboard is reachable
curl -o /dev/null -sw "%{http_code}\n" http://localhost:3001

The first command should return running. The curl should return 200. Log in, check that your monitors show a green heartbeat within one interval period, and trigger a manual test notification to confirm the alerting pipeline works.

Troubleshooting

Dashboard shows a blank screen or WebSocket error

This almost always means the reverse proxy is stripping WebSocket upgrade headers. Add Upgrade and Connection proxy headers as described in the nginx/Caddy docs for Socket.IO.

Ping monitors report "Permission denied"

On very old kernels or hardened systems, unprivileged ICMP may be blocked. Check sysctl net.ipv4.ping_group_range — it should include GID 0. As a workaround, switch to a TCP Port monitor on port 22 to test host reachability.

Container restarts in a loop

docker compose logs --tail=50 uptime-kuma

A corrupted SQLite database is the most common cause after an unclean shutdown. The logs will show an SQLite error. Stop the container, back up the volume, then try sqlite3 /var/lib/docker/volumes/uptime-kuma_uptime-kuma-data/_data/kuma.db "PRAGMA integrity_check;" to assess damage.

Notifications fire for monitors that are actually up

Reduce false positives by increasing Retries (under the monitor's Advanced section) to 2 or 3. Uptime Kuma will only mark a monitor down after that many consecutive failures.