Every service you run will go down eventually. The question is whether you find out from a customer tweet or from your own monitoring. Uptime Kuma is a self-hosted, open-source monitoring tool that checks your services from the outside and alerts you through your preferred channels before anyone else notices. It supports HTTP, TCP, ping, Docker container health, and even keyword checks on web pages. The interface is clean, the setup is fast, and unlike SaaS alternatives, there are no per-monitor pricing tiers.
This guide walks through a complete Uptime Kuma setup using Docker Compose, from first container start to production alerting. For Caddy-based deployments, see our Caddy production guide. For NGINX + PostgreSQL setups, check the NGINX production guide.
What You Need Before Starting
Uptime Kuma is lightweight. A $5 VPS handles hundreds of monitors without strain:
- A Linux server (Ubuntu 22.04 or 24.04 LTS recommended)
- Docker Engine 24.x+ and Docker Compose v2 installed
- At least 512 MB RAM and 2 GB disk space
- A domain or subdomain (optional, but recommended for HTTPS)
- An alerting endpoint: Telegram bot token, Discord webhook, email SMTP, or Pushover key
That is it. No database server, no complex dependencies. Uptime Kuma uses SQLite by default and stores everything in a single data directory.
Project Structure and Docker Compose
Create a dedicated directory and write a minimal Compose file. We bind the data directory to the host for easy backups and use a healthcheck so Docker can restart the container if it becomes unresponsive:
sudo mkdir -p /opt/uptime-kuma
sudo chown $USER:$USER /opt/uptime-kuma
cd /opt/uptime-kumaCreate the docker-compose.yml:
services:
uptime-kuma:
image: louislam/uptime-kuma:2
container_name: uptime-kuma
restart: always
ports:
- "127.0.0.1:3001:3001"
volumes:
- ./data:/app/data
environment:
- TZ=UTC
- UMASK=0022
networks:
- kuma_network
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3001"]
interval: 30s
retries: 3
start_period: 10s
timeout: 5s
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
networks:
kuma_network:
driver: bridgeWe bind to 127.0.0.1:3001 so Uptime Kuma is only reachable through a reverse proxy. If you are testing locally, change this to 3001:3001 temporarily.
Starting the Container and First Login
Launch the stack and verify it starts cleanly:
docker compose up -d
docker compose ps
docker compose logs --tail 20Wait about 10 seconds for initialization, then open your browser:
http://your-server-ip:3001The first visit prompts you to create an admin account. Use a strong password and store it in your password manager. There is no password recovery mechanism.
Reverse Proxy and HTTPS
For production, put Uptime Kuma behind a reverse proxy with TLS. Here is a minimal NGINX configuration:
server {
listen 80;
server_name status.example.com;
return 301 https://\$server_name\$request_uri;
}
server {
listen 443 ssl http2;
server_name status.example.com;
ssl_certificate /etc/letsencrypt/live/status.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/status.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:3001;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade \$http_upgrade;
proxy_set_header Connection "upgrade";
}
}The WebSocket headers are required for the real-time status page and live monitor updates. Without them, the dashboard will feel sluggish and stale.
Obtain certificates with certbot:
sudo certbot --nginx -d status.example.com
sudo systemctl reload nginxConfiguring Monitors
Uptime Kuma supports more than simple HTTP pings. Here are the monitor types you will use most often:
HTTP Website Monitor
The default. Uptime Kuma sends a GET request and checks for a 2xx status code. Set the heartbeat interval to 60 seconds for production sites and 300 seconds for internal tools.
TCP Port Monitor
Use this for databases, SSH, or any service that speaks TCP but not HTTP. Specify the host and port. Uptime Kuma attempts a socket connection and reports success or failure.
Docker Container Monitor
Monitor containers running on the same host. Uptime Kuma uses the Docker socket to check container health status. Mount the socket in your Compose file:
services:
uptime-kuma:
volumes:
- ./data:/app/data
- /var/run/docker.sock:/var/run/docker.sock:roThen select Docker Container as the monitor type and choose the container name from the dropdown.
Keyword Monitor
Check that a specific string exists on a web page. Useful for verifying that a CMS is rendering content correctly or that an API response contains expected data. Uptime Kuma fetches the page and searches for the keyword in the response body.
Setting Up Alerts
A monitor without alerting is just a dashboard. Configure notification channels in Settings, then attach them to individual monitors or monitor groups.
Telegram Alerts
Create a bot with @BotFather, copy the token, and paste it into Uptime Kuma's Telegram notification settings. Add your chat ID (find it with @userinfobot) and test the connection.
Discord Webhook
In your Discord server, create a webhook for the channel where alerts should appear. Copy the webhook URL and paste it into Uptime Kuma. You can customize the message format and mention roles.
Email via SMTP
For teams that live in email, configure SMTP in the notification settings. Use an app-specific password if you use Gmail or Microsoft 365. Test sends a confirmation message before you save.
Status Pages and Public Dashboards
Uptime Kuma can generate public status pages that show only the monitors you select. This is useful for customer-facing transparency. Create a status page from the sidebar, add monitors, and choose a slug:
https://status.example.com/status/my-companyStatus pages are read-only and do not expose monitor configuration or historical data beyond what you choose to display.
Backups and Updates
Backing Up the Data Directory
Since Uptime Kuma uses SQLite, backing up is a simple file copy. Schedule this daily:
#!/bin/bash
BACKUP_DIR="/opt/backups/uptime-kuma"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
tar czf $BACKUP_DIR/uptime-kuma_$TIMESTAMP.tar.gz -C /opt/uptime-kuma data
find $BACKUP_DIR -name '*.tar.gz' -mtime +14 -deleteUpdating Uptime Kuma
Updates are pull and recreate:
docker compose pull
docker compose up -d
docker compose logs --tail 20Tips and Troubleshooting
Monitor shows down but the site is up
Check the monitor timeout setting. Some CDNs or slow backends need more than the default 48 seconds. Increase the timeout and retry count. Also verify DNS resolution from the Uptime Kuma container:
docker exec uptime-kuma nslookup example.comAlerts are not firing
Confirm the notification channel is configured and tested. Each channel has a Test button in the settings. If testing works but alerts do not fire, check that the monitor has the notification channel attached in its settings.
Status page shows certificate errors
Uptime Kuma validates TLS certificates by default. If you monitor a site with a self-signed cert, disable certificate verification in the monitor settings. Do not do this for production sites.
High memory usage
Each monitor consumes a small amount of memory. With hundreds of monitors, the total adds up. Reduce the heartbeat interval for non-critical services or split monitors across multiple Uptime Kuma instances.
Container healthcheck fails
If the Docker healthcheck repeatedly fails, ensure curl is available inside the container. The official image includes it, but custom images may not. You can override the healthcheck in Compose if needed.
Next Steps
You now have a self-hosted monitoring stack that watches your services, alerts your team, and displays public status pages. Uptime Kuma is simple enough to run on a hobby VPS and capable enough to handle production workloads.
For related deployment patterns, explore our other guides:
- Uptime Kuma Setup: The Self-Hosted Monitoring Stack You'll Actually Keep Running
- Production Guide: Deploy Uptime Kuma with Docker Compose + Caddy on Ubuntu
- Production Guide: Deploy Uptime Kuma with Docker Compose + NGINX + PostgreSQL on Ubuntu
Need help scaling your monitoring to hundreds of endpoints, integrating with PagerDuty or Opsgenie, or building custom status page branding? Contact our team for enterprise monitoring consulting and managed infrastructure services.