Uptime Kuma: know when your home lab goes offline

Check the service before someone tells you it is down

Uptime Kuma is a self-hosted monitoring project with checks for websites, TCP ports, DNS and other endpoints. It can send notifications and publish selected results on status pages. Its code is MIT-licensed.

The useful question is specific: can this machine reach this service in the way a person needs? A web page responding, a TCP port accepting connections and a complete customer workflow succeeding are different checks. This guide follows the project documentation reviewed on November 2, 2026; the diagrams are examples, not araNET monitoring measurements.

Start with one monitor host

Use a machine that stays on and can reach the services you intend to check. Install Docker Engine and its Compose plugin using the official instructions. Keep Kuma’s data in a local Docker volume. The project does not support NFS for its data directory.

A monitor running on the same server as every application will disappear when that server loses power. For that reason, our recommendation is to keep an independent external check for a public website as well. A local monitor is valuable for your LAN, but its viewpoint has limits.

Install a loopback-only trial

Create a fresh directory:

mkdir kuma-guide
cd kuma-guide

Save this as compose.yaml. It uses the project’s version-2 image and a persistent volume. The loopback binding keeps the setup screen on this host until you deliberately arrange access.

services:
  monitor:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - monitor-data:/app/data

volumes:
  monitor-data:

Review the file, then start the service and check its state:

docker compose up -d
docker compose ps

Open http://localhost:3001 on the host. If Docker is on another machine, use an SSH tunnel from your computer, replacing the username and hostname below with your own:

ssh -L 3001:127.0.0.1:3001 your-user@your-server

Leave that tunnel open and browse to http://localhost:3001 on your computer. Create the administrator account before widening access. You do not need to mount the Docker socket to monitor ordinary website or TCP endpoints.

Add checks that answer different questions

For a first HTTP monitor, choose an HTTPS page you own, give it a recognizable name and use a modest interval such as 60 seconds. That interval is an example setting, not a performance claim. Save it and inspect several results before adding more checks.

• HTTP: does the chosen page return an acceptable response?
• Keyword: does an expected phrase appear, rather than just an error page with a successful HTTP status?
• TCP: can the monitor establish a connection to the configured port?
• DNS: does the selected resolver return the expected record?

The project README lists supported monitor types. Choose a check that matches the failure you want to catch. A green HTTP check cannot prove that login, payments or file uploads work.

Test the alert and the recovery

Choose a supported notification destination you control. Configure it using the notification guide, run its test action and confirm the message arrives. Then attach that notification configuration to the intended monitor.

For a safe end-to-end test, point a disposable monitor at a test endpoint you control. Make that test endpoint unavailable, wait for the configured failure conditions and verify the alert. Restore it and confirm the recovery notification. Leave production services alone during this test.

Write down which check failed, when the message arrived and what restored it. Tune retries and intervals around useful signals rather than an inbox full of transient warnings.

Share only the status people need

A status page can show a selected group of monitors. Review names and descriptions before sharing; a public page should not reveal private server addresses or internal service details. The administration interface and the public status page have different audiences.

Preserve the monitoring history

Back up the persistent volume with an application-consistent process; stop the service before a simple file-level copy. Keep the Compose configuration alongside the recovery notes. Read the update instructions before changing major versions.

For routine image updates after that review and backup:

docker compose pull
docker compose up -d

Open the dashboard again, confirm the monitors are still present and repeat a notification test. Monitoring becomes useful when its own alerts and recovery are checked too.