Monitor Docker Containers with Uptime Kuma

This guide shows you how to set up Uptime Kuma to monitor your Docker containers. You’ll create a monitoring dashboard that checks if your containers are running, restarts them when they fail, and alerts you via email, Telegram, or other channels. You’ll need a server with Docker installed and basic familiarity with the command line.

What You’ll Need

• A server or VPS with Docker and Docker Compose installed
• SSH access to that server
• A domain name or IP address to access the Uptime Kuma web interface (optional but recommended)
• A notification channel (email, Telegram, Slack, etc.) for alerts

Step-by-Step

1. Create a directory for Uptime Kuma. SSH into your server and run: mkdir uptime-kuma && cd uptime-kuma
2. Create a docker-compose.yml file. Use a text editor (nano or vim) to create docker-compose.yml with the following content:

   version: '3.8'
   services:
     uptime-kuma:
       image: louislam/uptime-kuma:1
       container_name: uptime-kuma
       volumes:
         - ./data:/app/data
       ports:
         - "3001:3001"
       restart: unless-stopped

   This maps port 3001 on your server to the container’s web interface.

3. Start Uptime Kuma. Run docker-compose up -d to pull the image and start the container. Wait a few seconds for it to initialize.
4. Access the web interface. Open your browser and go to http://YOUR_SERVER_IP:3001. You’ll see a setup screen. Create an admin username and password, then log in.
5. Add a monitor for a Docker container. Click “Add New Monitor”. Choose “Docker” as the monitor type. In the “Docker Host” field, enter the Docker socket path. By default, use unix:///var/run/docker.sock. For the “Container Name”, enter the exact name of the container you want to monitor (e.g., nginx or my-app). Set the interval (e.g., 60 seconds) and choose a notification group if you have one. Click “Save”.
6. Test the monitor. Uptime Kuma will immediately check the container. If it’s running, the status will show “UP” (green). If not, it will show “DOWN” (red).
7. Set up notifications. Go to “Settings” > “Notifications”. Click “Add Notification”. Choose your preferred service (e.g., Telegram, Email, Discord). Fill in the required fields (like bot token, chat ID, or SMTP settings). Test the notification and save it.
8. Assign notifications to monitors. Edit the monitor you created, scroll to “Notification”, and select the notification you just set up. Save.
9. Enable auto-restart (optional). In the monitor settings, under “Advanced Settings”, check “Auto Restart” to have Uptime Kuma restart the container if it goes down. This requires the Docker socket to be accessible.
10. Secure the web interface (recommended). If you’re exposing Uptime Kuma to the internet, set up a reverse proxy with HTTPS (e.g., using Nginx or Caddy) and a domain name. This keeps your admin credentials and Docker socket safe.

Common Mistakes

• Wrong Docker socket path. On some systems, the socket is at unix:///var/run/docker.sock but if you’re using Docker Desktop or a remote host, you need a different URL like tcp://host:2375. Double-check your Docker setup.
• Container name mismatch. Uptime Kuma uses the exact container name (not the image name). Use docker ps to see the actual names.
• Port conflict. If port 3001 is already in use, change the left side of the port mapping (e.g., 8080:3001) and access it on port 8080.
• Missing data volume. If you don’t mount a volume for /app/data, all your monitors and settings are lost when the container is recreated.

Tips

• Use a dedicated network for your containers so Uptime Kuma can reach them by name (e.g., nginx instead of an IP).
• Set up a “Heartbeat” monitor (HTTP or Ping) for your entire server in addition to container-specific monitors.
• Use the “Status Page” feature in Uptime Kuma to create a public page showing the health of your services.
• Monitor not just if the container is running, but also if it’s responding correctly by adding an HTTP monitor pointing to the container’s internal port.

Troubleshooting

• Monitor shows “DOWN” but the container is running. Check if the container name is correct. Also, ensure Uptime Kuma has access to the Docker socket. If you’re using a remote Docker host, the socket path may need to be tcp://IP:2375 and you must enable the Docker API on that host.
• Cannot access the web interface. Check if the container is running with docker ps. Verify the port mapping with docker port uptime-kuma. Ensure your firewall allows incoming traffic on that port.
• Auto-restart doesn’t work. The Docker socket must be mounted into the Uptime Kuma container. In your docker-compose.yml, add a volume: - /var/run/docker.sock:/var/run/docker.sock. Also, the container name must be exact.
• Notifications not sending. Test the notification in the settings. For email, check that your SMTP server allows less secure apps or uses the correct port (587 for TLS, 465 for SSL). For Telegram, ensure the bot token and chat ID are correct.
• Data loss after updating. Always back up the ./data directory before updating Uptime Kuma. You can copy it or use a Docker volume.

Frequently Asked Questions

Can I monitor containers on a different Docker host?

Yes. In the monitor settings, set the Docker Host to a remote Docker API endpoint (e.g., tcp://192.168.1.10:2375). You’ll need to configure the remote Docker daemon to listen on TCP and secure it with TLS.

Does Uptime Kuma restart containers automatically?

Yes, if you enable “Auto Restart” in the monitor’s advanced settings. It will run docker restart on the container when it goes down.

What notification methods are supported?

Uptime Kuma supports over 90 notification services, including Email, Telegram, Discord, Slack, Webhooks, and many more. You can set up multiple notifications per monitor.

Can I monitor containers that are not currently running?

Yes, you can add a monitor for any container name. Uptime Kuma will show it as “DOWN” until it starts. This is useful for containers that are stopped intentionally.

Is there a way to monitor container resource usage (CPU, memory)?

Uptime Kuma focuses on uptime, not resource metrics. For CPU/memory monitoring, consider using a tool like Prometheus with cAdvisor or Grafana.

Do I need to expose the Docker socket to the internet?

No. The Docker socket is only used internally by Uptime Kuma. You should never expose it to the internet. Use a reverse proxy for the web interface instead.

Related

• Create Databases in phpMyAdmin on Debian 12
• One Redis Instance for Multiple Websites: Safe Setup
• Realme C17: Snapdragon 460, 90Hz Display, 5000mAh Battery