Uptime Kuma Monitoring Stack

A Docker Compose setup for monitoring uptime and availability using Uptime Kuma.

Overview

Uptime Kuma is a self-hosted monitoring tool like Uptime Robot. Features include:

• Monitor HTTP(s), TCP, HTTP(s) Keyword, Ping, DNS Record, Docker Containers
• Notifications via multiple channels (Discord, Slack, Email, etc.)
• Status pages for public/private sharing
• Multi-language support

Security Note: By default, no ports are exposed to the host. The service communicates internally via Docker's network. For external access, use the included reverse proxy configuration or uncomment ports for local development.

Prerequisites

• Docker Engine 20.10 or later
• Docker Compose v2.0 or later

Quick Start

1. Initial Configuration

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env and set your server URL:

UPTIME_KUMA_SERVER=https://status.example.com

Note: Initial login credentials are set via the web interface during first setup, not in environment variables.

2. Start the Service

docker compose up -d

3. Verify Service

By default, the service port is not exposed to the host. The service communicates internally via Docker's network.

To access Uptime Kuma from the host, you have two options:

Option A: Expose port (for local development/testing)

Edit docker-compose.yaml and add the port mapping:

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

Then restart and access at http://localhost:3001

Option B: Use a reverse proxy (recommended for production)

Use docker-compose.override.yaml to configure a reverse proxy (e.g., Caddy, Nginx) that handles external access with HTTPS.

4. Initial Setup

1. Access Uptime Kuma (see "Verify Service" section above for access methods)
2. Create your admin account on first visit
3. Start adding monitors for your services

Service Details

Service	Port	Exposed by Default	Description
Uptime Kuma	3001	No	Monitoring dashboard and API

Note: The port is not exposed in docker-compose.yaml by default for security. Services communicate internally via Docker network names (e.g., uptime-kuma:3001).

Configuration Files

• docker-compose.yaml - Main service definition
• docker-compose.override.yaml - Optional proxy configuration, use docker-compose.override.yaml as template
• .env - Environment variables (create from .env.example)

Persistent Data Storage

The service uses a local directory to persist data across container restarts:

• ./data: Stores Uptime Kuma database, configuration, screenshots, and uploads

This directory is bind-mounted into the container, making your data easily accessible from the host filesystem. Your data will be preserved even if you stop or recreate the container.

Important: This directory is excluded from git via .gitignore to prevent committing sensitive data.

Reverse Proxy Configuration

The included docker-compose.override.yaml configures Uptime Kuma to work with an external Caddy reverse proxy. This is the recommended approach for production deployments.

Requirements:

• An external Caddy container with Docker proxy support
• The caddy network created: docker network create caddy
• UPTIME_KUMA_SERVER variable set in .env to your domain

The override file automatically:

• Connects Uptime Kuma to the Caddy network
• Sets up automatic HTTPS via Caddy labels
• Keeps the service secure by not exposing ports directly

Monitoring Services on the Same Host

Via Docker Network

Use the container name as the host in monitor configuration:

• Example: http://other-container:3001
• Find container names with: docker ps

Important: Avoid redirects when monitoring services. Use the full path:

• Good: http://example-service/wiki/Main_Page
• Bad: http://example-service (if it redirects)

Via Docker Socket

To monitor Docker containers directly, see: louislam/uptime-kuma#6585

Useful Commands

# View logs
docker compose logs -f

# Stop service (data persists in local directory)
docker compose down

# Restart service
docker compose restart

# Check service status
docker compose ps

# Access service from command line (if port not exposed)
docker compose exec uptime-kuma wget -qO- http://uptime-kuma:3001

# Backup data (stop service first)
docker compose down
tar czf uptime-kuma-backup-$(date +%Y%m%d).tar.gz data

# Restore data (stop service first)
docker compose down
tar xzf uptime-kuma-backup-YYYYMMDD.tar.gz

# Reset all data (WARNING: deletes all monitors and configuration)
docker compose down -v && rm -rf ./data/*

# Update to latest version
docker compose pull
docker compose up -d

Troubleshooting

Cannot access service from host:

• By default, the port is not exposed. See "Verify Service" section for access options.
• If you added port mapping in docker-compose.yaml, restart: docker compose restart

Monitoring other containers fails:

• Ensure containers are on the same Docker network
• Use container names, not localhost/127.0.0.1
• Verify the target container is running: docker ps

Port conflict (if exposing port):

• Check if port 3001 is already in use: netstat -tulpn | grep 3001
• Modify port mapping in docker-compose.yaml if needed

Permission denied errors in data directory:

• The data directory is owned by the container user (root)
• To access files: sudo ls -la data/
• To backup: sudo tar czf backup.tar.gz data/

Lost admin password:

• Stop the container
• Delete or reset the database: sudo rm data/kuma.db*
• Start container and set up a new admin account
• WARNING: This will delete all monitors and data

Updating

To update Uptime Kuma to the latest version:

docker compose pull
docker compose up -d

The container will automatically handle database migrations if needed.