Kuma Container Sync

Auto-discovers Docker containers on a host and reconciles Uptime Kuma Docker monitors for them, organizing monitors under a host-named group and optionally attaching an existing notification.

Features

• Discover Docker containers via the Docker socket.
• Create Uptime Kuma Docker monitors for new containers.
• Keep existing monitors grouped under a host-specific monitor group.
• Optionally attach an existing Uptime Kuma notification by name.
• Allow individual containers to opt out with a Docker label.
• Reconcile periodically using SYNC_INTERVAL (idempotent loop).

Requirements

• Uptime Kuma instance reachable at KUMA_URL with a user that can create/edit monitors.
• A Docker Host configured in Uptime Kuma matching DOCKER_HOST_NAME.
• Access to the Docker socket on the host (e.g., /var/run/docker.sock).

Environment Variables

• KUMA_URL (default: http://uptime-kuma:3001): Base URL of your Uptime Kuma instance.
• KUMA_USER (required): Uptime Kuma username.
• KUMA_PASS (required): Uptime Kuma password.
• DOCKER_HOST_NAME (required): Name of the Docker Host entry in Uptime Kuma to associate container monitors with.
• KUMA_GROUP_NAME (default: value of DOCKER_HOST_NAME): Monitor group name to place all container monitors under.
• NOTIFICATION_NAME (optional): Name of an existing Uptime Kuma notification to attach to created monitors. If not found or not provided, monitors are created without notifications.
• SYNC_INTERVAL (default: 300): Seconds to wait between sync runs.
• LOGIN_RETRIES (default: 5): Number of retry attempts for logging into Uptime Kuma.
• KUMA_SYNC_CONFIG_PATH (default: /config/kuma-sync-config.json): JSON configuration file path.

Exclude a container from monitoring

Add the following label to any container that should not receive an automatically created Docker monitor:

labels:
  kuma.monitor.enabled: "false"

The synchronizer leaves any existing monitor untouched; it only prevents new monitor creation and automatic group assignment for the labeled container.

For containers that cannot be labeled, such as short-lived CI job containers, exclude one or more name prefixes with a kuma-sync-config.json file:

{
  "exclude_names": [
    "scheduled-backup"
  ],
  "exclude_name_prefixes": [
    "FORGEJO-ACTIONS-TASK-",
    "temporary-"
  ]
}

exclude_names matches complete container names; exclude_name_prefixes matches dynamic container families such as CI jobs.

Mount the configuration file at /config/kuma-sync-config.json, or set KUMA_SYNC_CONFIG_PATH to a different location.

See monitor.py for details.

Quick Start (Docker)

Build the image:

docker build -t ghcr.io/benrhughes/kuma-container-sync:latest .

Run the container (maps Docker socket and sets env):

docker run -d \
  --name kuma-container-sync \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e KUMA_URL="http://uptime-kuma:3001" \
  -e KUMA_USER="your-user" \
  -e KUMA_PASS="your-pass" \
  -e DOCKER_HOST_NAME="Your Docker Host" \
  -e KUMA_GROUP_NAME="Your Host Group" \
  -e NOTIFICATION_NAME="Your Notification" \
  -e SYNC_INTERVAL=300 \
  ghcr.io/benrhughes/kuma-container-sync:latest

Notes:

• Ensure DOCKER_HOST_NAME matches an existing Docker Host in Uptime Kuma.
• If NOTIFICATION_NAME doesn’t exist, monitors will be created without notifications.
• Image includes a Docker HEALTHCHECK that fails if no successful sync has occurred recently (threshold ≈ 2 * SYNC_INTERVAL + 60s).

Architectures: Multi-arch images are published (linux/amd64, linux/arm64). Docker will select the right variant automatically.

Docker Compose Example

Create a docker-compose.yml file:

services:
  kuma-container-sync:
    image: ghcr.io/benrhughes/kuma-container-sync:latest
    container_name: kuma-container-sync
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - KUMA_URL=http://uptime-kuma:3001
      - KUMA_USER=your-user
      - KUMA_PASS=your-pass
      - DOCKER_HOST_NAME=Your Docker Host
      # Optional environment variables
      # - KUMA_GROUP_NAME=Your Host Group
      # - NOTIFICATION_NAME=Your Notification
      # - SYNC_INTERVAL=300
      # - LOGIN_RETRIES=5
    restart: unless-stopped

Run it with:

docker compose up -d

Create a Docker Host in Uptime Kuma

Before running this tool, create a Docker Host entry in your Uptime Kuma instance:

1. In Uptime Kuma, go to Settings → Docker Hosts.
2. Click “Add New”.
3. Set Name to the exact value you will use for DOCKER_HOST_NAME.
4. Configure the Docker connection (e.g., local socket or remote engine) per your Kuma deployment.
5. Save. The name must match DOCKER_HOST_NAME so monitors can link to this host.

Local Run (Python)

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export KUMA_URL="http://uptime-kuma:3001"
export KUMA_USER="your-user"
export KUMA_PASS="your-pass"
export DOCKER_HOST_NAME="Your Docker Host"
python monitor.py

Files

• monitor.py: Sync logic.
• Dockerfile: Container build.
• requirements.txt: Python dependencies.

Compatibility

• This tool targets Uptime Kuma 2.x. Monitor group creation currently uses a low-level client call because a public helper may not be available in all uptime-kuma-api versions used in the wild. Dependencies are constrained in requirements.txt to reduce breakage.

License

Released under the AGPL-3.0 license. See LICENSE.