Uptime Kuma: The Self-Hosted Monitoring Solution Your Homelab Deserves

It’s 3 AM. Your home server rack hums quietly in the corner. Somewhere, a service crashed - maybe it was that container update you ran yesterday, or perhaps the database connection timed out. You won’t know until morning when someone texts you: “Hey, is your site down?”

For homelab enthusiasts and self-hosters, this scenario is all too familiar. Commercial monitoring solutions exist, but they come with subscription fees, data privacy concerns, and artificial limits. What if there was a better way?

Enter Uptime Kuma - an open-source, self-hosted monitoring tool that’s become the go-to choice for over 130 million Docker pulls. Let’s explore why it’s earned that popularity and how you can set it up in your own environment.

What is Uptime Kuma?

Uptime Kuma is a free, open-source monitoring solution created by Louis Lam. It tracks the uptime and performance of your websites, applications, and services - all from your own infrastructure. With 80,000+ GitHub stars and an active community, it’s one of the most popular self-hosted monitoring tools available.

The name “Kuma” comes from the Japanese word for “bear” - fitting for a tool that watches over your services with protective vigilance.

Why Self-Hosted Monitoring?

Before diving into setup, let’s address the elephant in the room: why self-host when services like UptimeRobot and Pingdom exist?

Data Privacy. Every ping, every response time, every incident gets logged somewhere. With hosted services, that data sits on someone else’s servers. For homelabbers running personal services or small businesses handling internal applications, keeping that data local matters.

No Artificial Limits. Free tiers on commercial services typically cap at 50 monitors with 5-minute check intervals. Uptime Kuma? Unlimited monitors. Check intervals as fast as 1 second. No surprise paywalls.

Zero Subscription Fees. The math is simple: free forever. No per-seat pricing. No “premium” features locked behind paywalls. Everything works out of the box.

:::tip[Self-Hosting Isn’t For Everyone] If you don’t have infrastructure to run it on or need guaranteed SLA-backed support, commercial solutions might be better. Uptime Kuma shines when you already have a server, homelab, or NAS running. :::

Getting Started: Installation in Minutes

The fastest way to get Uptime Kuma running is with Docker. If you have Docker installed, you’re minutes away from having a monitoring dashboard.

Quick Docker Deployment

Create a directory and start the container:

mkdir uptime-kuma
cd uptime-kuma

docker run -d \
  --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

That’s it. Navigate to http://your-server:3001 and complete the initial setup wizard. Create your admin account, and you’re ready to start adding monitors.

Docker Compose (Recommended)

For a more maintainable setup, use Docker Compose:

version: "3"
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./uptime-kuma:/app/data
    ports:
      - 3001:3001

docker compose up -d

:::warning[NFS Storage Not Supported] Uptime Kuma stores data in SQLite, which doesn’t work reliably over NFS. Use local storage for the /app/data volume. :::

Secure with a Reverse Proxy

For production deployments, don’t expose port 3001 directly. Put it behind a reverse proxy with HTTPS:

Caddy (Simplest Option):

status.yourdomain.com {
    reverse_proxy localhost:3001
}

Caddy automatically handles HTTPS with Let’s Encrypt. One config line and you’re done.

Nginx (More Control):

server {
    listen 443 ssl http2;
    server_name status.yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/status.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/status.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

The Upgrade and Connection headers are crucial - Uptime Kuma uses WebSockets for real-time status page updates.

Monitor Everything: Supported Types

Uptime Kuma isn’t limited to simple HTTP checks. It supports 20+ monitor types:

Monitor Type	Use Case
HTTP(s)	Web endpoints, health checks, API status
TCP Port	Check if ports are accessible
Ping	ICMP connectivity tests
DNS Record	Verify DNS resolution
Docker Container	Monitor container health status
Database (PostgreSQL, MySQL, MongoDB, Redis)	Database availability
WebSocket	Real-time service endpoints
gRPC	Microservice health checks
SNMP	Network device monitoring
Push	Heartbeat monitors for CI/CD pipelines

The Push Monitor: A Dev’s Best Friend

Push monitors are unique - they don’t actively check your service. Instead, your service calls Uptime Kuma:

# Call this at the end of your backup script
curl "https://uptime-kuma.example.com/api/push/TOKEN?status=up&msg=Backup%20completed"

If Uptime Kuma doesn’t receive a call within the expected interval, it alerts you. Perfect for:

• Backup scripts that should run nightly
• Cron jobs and scheduled tasks
• CI/CD pipeline health checks
• Any scheduled job you want to verify

Notifications: 90+ Ways to Get Alerted

This is where Uptime Kuma truly shines. While free tiers on commercial services offer 4-5 notification options, Uptime Kuma supports over 90 integrations.

Popular Notification Channels

Messaging:

• Telegram, Discord, Slack, Matrix, Microsoft Teams
• Mattermost, Rocket.Chat, Google Chat

Push Notifications:

• Pushover, Pushbullet, NTFY, Gotify
• Web Push (browser notifications)

Email:

• SMTP (any email server)
• Resend (transactional email service)

SMS:

• Twilio, Aliyun SMS, SerwerSMS

Incident Management:

• PagerDuty, Opsgenie, Google Sheets

Smart Home:

• Home Assistant integration

Notification Groups

Create notification groups for different contexts:

• Critical Services → PagerDuty + SMS + Phone call
• Homelab Services → Telegram + Discord
• Development → Slack only
• Status Updates → Email subscribers

Configure escalation policies: retry notifications, add delays between attempts, or chain multiple services in sequence.

Status Pages: Your Public Face

Every monitored service can appear on a public status page. Create multiple status pages for different audiences:

• Internal services → Internal status page for team
• Customer-facing → Public status page with custom branding

Features

• Real-time updates via WebSocket (no page refresh needed)
• Custom logos, colors, and CSS
• Dark/light mode support
• Maintenance window announcements
• Incident history tracking
• Uptime percentage displays
• Custom domain mapping

:::tip[Status Badge Embeds] Add uptime badges to any documentation or dashboard:

![Status](https://status.yourdomain.com/api/badge/TOKEN)

Perfect for GitHub READMEs, Notion pages, or internal wikis. :::

Home Assistant Integration

For smart home enthusiasts, Uptime Kuma integrates natively with Home Assistant (added in 2025.8). All your monitors become sensors.

Setup

1. Create an API key in Uptime Kuma (Settings → API Keys)
2. Add the Uptime Kuma integration in Home Assistant
3. Enter your Uptime Kuma URL and API key

Available Sensors

Each monitor creates several sensors:

• sensor.uptime_kuma_service_name - Current status (up/down/pending/maintenance)
• sensor.uptime_kuma_service_name_response_time - Response time in milliseconds
• sensor.uptime_kuma_service_name_cert_expiry - Days until SSL certificate expires

Automation: Status Light

Turn a physical indicator light red when services are down:

automation:
  - alias: "Service Status Light"
    triggers:
      - trigger: state
        entity_id: sensor.uptime_kuma_homeassistant
    actions:
      - choose:
          - conditions:
              - condition: state
                entity_id: sensor.uptime_kuma_homeassistant
                state: "down"
            sequence:
              - action: light.turn_on
                data:
                  color_name: red
                target:
                  entity_id: light.status_indicator
          - conditions:
              - condition: state
                entity_id: sensor.uptime_kuma_homeassistant
                state: "up"
            sequence:
              - action: light.turn_on
                data:
                  color_name: green
                target:
                  entity_id: light.status_indicator

Now your smart home physically alerts you when something goes wrong.

Best Practices for Production

Security

1. Enable Two-Factor Authentication - Every admin account should have 2FA enabled. Use TOTP apps like Authy or Google Authenticator.

2. Run Behind a Reverse Proxy - Never expose Uptime Kuma directly to the internet. Use Nginx, Caddy, or Traefik with HTTPS.

3. Bind to Localhost - If using a reverse proxy, bind Docker to localhost only:

   -p 127.0.0.1:3001:3001

   This prevents direct access even if the firewall is misconfigured.

4. Rotate API Keys - Create separate API keys for each integration. Rotate them regularly.

Performance

Resource Guidelines:

• Minimum: 512MB RAM, 1 CPU core
• Recommended: 1GB+ RAM for 100+ monitors
• Storage: Allow growth for heartbeat data

Monitoring Intervals:

• External services: 60-300 seconds is sufficient
• Internal services: 30-60 seconds works well
• Critical services: Consider 10-20 seconds
• Reserve sub-second intervals for very specific needs

Backup Strategy

Your monitoring data is valuable. Back it up regularly:

# Simple backup
docker cp uptime-kuma:/app/data ./uptime-kuma-backup-$(date +%Y%m%d)

# Or copy the volume
cp -r /var/lib/docker/volumes/uptime-kuma/_data ./backup/

Set up a cron job to run backups nightly. Store copies offsite.

Updates

Uptime Kuma development is active. To update:

docker pull louislam/uptime-kuma:2
docker stop uptime-kuma
docker rm uptime-kuma
# Re-run your original docker run command

Always check release notes for breaking changes before updating production.

Real-World Use Cases

The Homelab Dashboard

Monitor everything in your homelab:

• Proxmox host health
• Docker containers (via socket mount)
• Pi-hole DNS filtering
• Home Assistant instance
• NAS storage availability
• Reverse proxy endpoints
• Internal web applications

One dashboard, instant notifications when anything fails.

Small Business Internal Monitoring

Track internal business applications without subscription fees:

• Internal web apps
• Database servers
• VPN endpoints
• Client-facing services

Create internal status pages for stakeholders. Export uptime data for SLA reporting.

CI/CD Integration

Use push monitors in your deployment pipeline:

# GitHub Actions example
- name: Notify Uptime Kuma
  run: |
    curl "https://status.example.com/api/push/${{ secrets.UPTIME_KUMA_TOKEN }}?status=up&msg=Deployed%20${GITHUB_SHA}"

If deployments stop happening, you’ll know within the expected window.

Comparison with Alternatives

Feature	Uptime Kuma	Uptime Robot	Pingdom
Cost	Free	Freemium	Paid
Self-Hosted	✅	❌	❌
Monitor Limit	Unlimited	50 (free)	Varies
Check Interval	1s+	5 min (free)	1 min+
Status Pages	Unlimited	1 (free)	Paid
Notifications	90+	4 (free)	Limited
Data Privacy	Full control	Third-party	Third-party

The choice is clear when you have infrastructure to host it. Uptime Kuma wins on limits, features, and data control - with zero recurring costs.

Getting Started Checklist

Ready to set up Uptime Kuma? Here’s your quick-start checklist:

• Install Docker on your server
• Run the Uptime Kuma container
• Create admin account
• Set up reverse proxy with HTTPS
• Enable 2FA on your admin account
• Add your first monitors
• Configure notification channels
• Create a status page
• Set up automated backups
• Integrate with Home Assistant (optional)

Conclusion

Uptime Kuma fills a gap that commercial services created: powerful monitoring without subscription fees, data sovereignty, and no artificial limits. For the self-hosting community, it’s become the standard choice.

The setup takes minutes. The interface is intuitive. The features match or exceed paid alternatives. And best of all - it’s yours. Your data stays on your servers. Your monitors have no limits. Your status pages reflect your brand.

Whether you’re monitoring a homelab, small business infrastructure, or customer-facing applications, Uptime Kuma delivers enterprise-grade monitoring at the cost of… owning a server. Which you already do.

Resources:

• GitHub Repository
• Official Wiki
• Docker Hub
• Home Assistant Integration

Happy monitoring! 🐻