Monitor Your Homelab for Free

Here's what happens without monitoring: your Sonarr container silently crashes at 3 AM because the host ran out of disk. You don't notice until Friday evening when you check your downloads. Three days of missed automation. Or: your DNS server goes down. Half your services break because they can't resolve internal domains. You troubleshoot for 45 minutes before realizing the problem is DNS, not the individual services. Uptime Kuma watches your services and alerts you the moment something goes down. It's like having a NOC for your homelab, except it runs in a single Docker container and uses 50MB of RAM. What it monitors: - HTTP/HTTPS endpoints (checks for 200 status codes) - TCP ports (checks if a port is open and accepting connections) - Ping (ICMP echo) - DNS (checks if a domain resolves correctly) - Docker containers (checks container status directly) - Game servers, MQTT, Redis, PostgreSQL, MySQL, and more What it can't do: it doesn't collect metrics (CPU, RAM, disk). For that you'd need Prometheus + Grafana. But for "is it up?" monitoring, Uptime Kuma is the fastest path to coverage.

Create a dedicated directory for Uptime Kuma:

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

Uptime Kuma is a single container with a single volume. Dead simple:

cat > ~/docker/uptime-kuma/docker-compose.yml << 'COMPOSE'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - uptime-kuma-data:/app/data
    networks:
      - monitor-net

networks:
  monitor-net:
    driver: bridge

volumes:
  uptime-kuma-data:
COMPOSE

Bring up the container:

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

Check the container status and test the web UI:

docker ps --filter name=uptime-kuma --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
echo '---'
curl -s -o /dev/null -w 'HTTP %{http_code}' http://localhost:3001

Container should show "Up" status, and curl should return "HTTP 200". If port 3001 is in use: sudo ss -tulnp | grep ':3001' Change the host port in docker-compose.yml (e.g., 3002:3001) and restart. If the container keeps restarting: docker logs uptime-kuma Common issue: corrupted database on first run (rare). Fix: docker compose down, remove the volume (docker volume rm uptime-kuma_uptime-kuma-data), and start again.

Open your browser and navigate to: http://YOUR_SERVER_IP:3001 You'll be prompted to create an admin account. Choose a strong password — this is the only account that can manage monitors. After creating the account, you'll land on the empty dashboard.

Click "Add New Monitor" in the dashboard. Let's start with the most common type — HTTP monitoring. For a web service (like Sonarr on 192.168.1.20:8989): - Monitor Type: HTTP(s) - Friendly Name: Sonarr - URL: http://192.168.1.20:8989 - Heartbeat Interval: 60 (checks every 60 seconds) - Retries: 3 (marks as down after 3 consecutive failures) - Accepted Status Codes: 200-299 Click "Save" at the bottom. Within 60 seconds, you should see the first heartbeat appear on the dashboard — a green dot if the service is up, red if it's down.

Add monitors for different service types: TCP Port (for services without a web UI, like SSH): - Monitor Type: TCP Port - Hostname: 192.168.1.x - Port: 22 - Friendly Name: SSH on .x Ping (for checking if a host is alive): - Monitor Type: Ping - Hostname: 192.168.1.x - Friendly Name: Proxmox Host DNS (for checking your DNS server): - Monitor Type: DNS - Hostname: google.com - DNS Server: 192.168.1.12 - Friendly Name: Technitium DNS - This checks that your DNS server can resolve google.com Docker Container (if Uptime Kuma runs on the same host): - Monitor Type: Docker Container - Container Name: vaultwarden - Docker Host: /var/run/docker.sock (mount it in docker-compose.yml first) To monitor Docker containers directly, add the socket to your compose file: volumes: - uptime-kuma-data:/app/data - /var/run/docker.sock:/var/run/docker.sock:ro

Here's a starter set that covers the critical path: 1. DNS server (DNS type) — if this dies, everything breaks 2. Reverse proxy (HTTP) — your single point of entry 3. Each major service (HTTP) — Sonarr, Radarr, Vaultwarden, etc. 4. Each VM host (Ping) — catches VMs that crash or lose network 5. Internet connectivity (HTTP to https://1.1.1.1) — catches ISP outages 6. NAS/storage (Ping + HTTP if it has a web UI) Don't go overboard on the first day. Start with 5-10 monitors for your most critical services. Add more over time as you learn what matters.

Monitoring without notifications is just a pretty dashboard. You need to be ALERTED when something goes down. In Uptime Kuma, go to Settings (gear icon) > Notifications > Setup Notification. Telegram (recommended — free, instant, works everywhere): 1. Message @BotFather on Telegram and create a new bot 2. Copy the bot token 3. Send a message to your bot, then visit: https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates to get your chat ID 4. In Uptime Kuma: Notification Type = Telegram, paste bot token and chat ID 5. Click "Test" to verify Discord: 1. In your Discord server, go to a channel > Settings > Integrations > Webhooks 2. Create a webhook and copy the URL 3. In Uptime Kuma: Notification Type = Discord, paste the webhook URL 4. Click "Test" to verify You can also use: Email (SMTP), Slack, Pushover, ntfy, Gotify, Matrix, and 80+ others. After setting up a notification, go back to each monitor and enable the notification under its settings. Monitors don't use notifications by default — you have to assign them.

Uptime Kuma can generate a public status page — useful for showing uptime to friends, family, or anyone else who uses your services. In the dashboard: 1. Click "Status Pages" in the left sidebar 2. Click "New Status Page" 3. Give it a name and slug (e.g., "homelab" at /status/homelab) 4. Add monitor groups (e.g., "Core Infrastructure", "Media", "Security") 5. Drag monitors into each group 6. Publish The status page is accessible at: http://YOUR_SERVER:3001/status/homelab Put this behind your reverse proxy for a clean URL: status.homelab.local { tls internal reverse_proxy 192.168.1.x:3001 }

Don't set everything to 5-second intervals. That wastes resources and spams your notification channels. Recommended intervals: - Critical services (DNS, reverse proxy): 30 seconds - Important services (Vaultwarden, mail): 60 seconds - Nice-to-have services (Sonarr, Radarr): 120 seconds - Infrastructure checks (ping, internet): 300 seconds Also set retries to 2-3. A single failed check doesn't mean the service is down — it might be a network hiccup or a slow response. Only alert after 2-3 consecutive failures.

To remove Uptime Kuma: 1. Stop and remove the container: cd ~/docker/uptime-kuma && docker compose down 2. Remove the data volume (deletes all monitors and history): docker volume rm uptime-kuma_uptime-kuma-data 3. Remove any Caddyfile/DNS entries you created for it Your other services are unaffected — Uptime Kuma is observation-only, it doesn't modify anything it monitors.