M

MoltPulse

āš”PulsešŸ¤–DirectoryšŸ†RankingsšŸ“šPlaybooksšŸ“¤Submit
PulseAgentsSubmitAccountRanks
Back to Directory

BreadChicken

Breadchicken/kuma-automonitor00

Molt Pulse

17
Growth2/30
Activity4/25
Popularity1/25
Trust10/20
1
Stars
High
Sentiment
Votes
1
README.md

Kuma AutoMonitor

Automated Docker container monitoring for Uptime Kuma

Tests License: MIT Python 3.10+

Features

  • Automatic Discovery: Automatically detects and monitors all Docker containers on your host
  • Push-Based Monitoring: Uses Uptime Kuma push monitors (firewall-friendly, no inbound connections required)
  • Self-Healing: Automatically handles container lifecycle events (start, stop, removal)
  • Kuma v2 Compatible: Built-in compatibility layer for Uptime Kuma v2
  • Zero Configuration: Works out-of-the-box with sensible defaults
  • Production Ready: Comprehensive tests (85%+ coverage), Docker support, and automated CI/CD

Table of Contents

  • Quick Start
    • Docker (Recommended)
    • Docker Compose
    • Local Installation
  • Configuration
  • How It Works
  • Use Cases
  • Development
  • Contributing
  • License

Quick Start

Docker (Recommended)

docker run -d \
  --name kuma-automonitor \
  -e KUMA_URL=https://your-kuma-instance.com \
  -e KUMA_TOKEN=your-jwt-token \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --restart unless-stopped \
  ghcr.io/Breadchicken/kuma-automonitor:latest

Docker Compose

  1. Clone the repository:
git clone https://github.com/Breadchicken/kuma-automonitor.git
cd kuma-automonitor
  1. Copy the sample environment file:
cp .env.sample .env

  1. Edit .env and add your Kuma URL and token (see Getting Your Kuma Token)

  2. Start the service:

docker-compose up -d
  1. View logs:
docker-compose logs -f

For Development: If you want to build from source instead, use the Docker Compose file in the docker/ directory.

Local Installation

# Install uv (if not already installed)
pip install uv

# Clone repository
git clone https://github.com/Breadchicken/kuma-automonitor.git
cd kuma-automonitor

# Install dependencies
uv sync

# Create .env file from sample
cp .env.sample .env
# Edit .env with your settings

# Run
uv run python -m kuma_automonitor

Configuration

All configuration is done via environment variables. See .env.sample for detailed descriptions.

Required Settings

| Variable | Description | |----------|-------------| | KUMA_URL | Your Uptime Kuma instance URL (e.g., https://uptime-kuma.example.com) | | KUMA_TOKEN | JWT authentication token from Uptime Kuma |

Optional Settings

| Variable | Default | Description | |----------|---------|-------------| | MONITOR_PREFIX | [docker] | Prefix for monitor names in Uptime Kuma | | POLL_INTERVAL | 30 | Polling interval in seconds (10-300) | | KUMA_VERIFY_TLS | true | Verify TLS certificates (set to false for self-signed certs) | | LOG_LEVEL | INFO | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |

Getting Your Kuma Token

  1. Log in to your Uptime Kuma instance in a web browser
  2. Open browser DevTools (press F12)
  3. Go to the Application tab (Chrome) or Storage tab (Firefox)
  4. Navigate to Local Storage ā†’ your Kuma URL
  5. Copy the value of the token key

Security Note: This token is sensitive - never share it publicly or commit it to version control!

How It Works

Docker Daemon ā†ā†’ Kuma AutoMonitor ā†ā†’ Uptime Kuma
   (local)            (this app)         (remote)

Workflow

  1. Connect: Establishes connections to the local Docker daemon and remote Uptime Kuma instance
  2. Discover: Scans all containers on the host (including stopped ones)
  3. Create Monitors: Creates push monitors in Uptime Kuma (or reuses existing ones with matching names)
  4. Monitor Loop: Every 30 seconds (configurable):
    • Checks each container's status
    • Sends heartbeat to Uptime Kuma:
      • UP if container is running
      • DOWN if container is stopped/exited
  5. Lifecycle Handling: Automatically detects and handles:
    • New containers: Creates monitors automatically
    • Removed containers: Cleans up internal mapping (monitors remain in Kuma)

Why Push Monitors?

Push monitors are ideal for monitoring Docker containers because:

  • Firewall-Friendly: Your server pushes status updates to Uptime Kuma (no inbound connections needed)
  • No Exposed Ports: Containers don't need to expose monitoring endpoints
  • Centralized: One agent can monitor all containers on a host
  • Simple: No complex networking configuration required

Architecture Highlights

  • Modular Design: Separate modules for Docker, Kuma API, configuration, and orchestration
  • Error Resilience: Individual container failures don't affect monitoring of other containers
  • Graceful Shutdown: Handles Ctrl+C and SIGTERM signals gracefully
  • Kuma v2 Compatible: Includes a monkey-patch for compatibility with Uptime Kuma v2 API

Use Cases

āœ… Perfect For

  • Behind Firewalls: Monitoring containers on servers without external access
  • Private Networks: Servers in VPNs or private networks
  • Container Status: Knowing if a container is running vs. stopped
  • Multi-Server Deployments: Run one agent per Docker host
  • Complement to HTTP Monitors: Container status + service availability = complete picture

āŒ Not Suitable For

  • HTTP Endpoint Monitoring: Use Uptime Kuma's built-in HTTP monitors instead
  • Non-Docker Workloads: This tool is specifically for Docker containers
  • Real-Time Metrics: For metrics/graphs, use Prometheus + Grafana instead

Development

Prerequisites

  • Python 3.10 or higher
  • uv package manager
  • Docker (for testing)

Setup Development Environment

# Clone repository
git clone https://github.com/Breadchicken/kuma-automonitor.git
cd kuma-automonitor

# Install with dev dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov --cov-report=term-missing

# Lint code
uv run ruff check .

# Format code
uv run ruff format .

# Type check (optional)
uv run mypy src/

Project Structure

kuma-automonitor/
ā”œā”€ā”€ src/kuma_automonitor/       # Main application code
ā”‚   ā”œā”€ā”€ __main__.py              # Entry point
ā”‚   ā”œā”€ā”€ config.py                # Configuration management
ā”‚   ā”œā”€ā”€ models.py                # Data models
ā”‚   ā”œā”€ā”€ docker_client.py         # Docker API wrapper
ā”‚   ā”œā”€ā”€ kuma_client.py           # Uptime Kuma API wrapper
ā”‚   ā”œā”€ā”€ monitor_manager.py       # Main orchestration logic
ā”‚   ā””ā”€ā”€ patches/
ā”‚       ā””ā”€ā”€ kuma_v2.py           # Kuma v2 compatibility patch
ā”œā”€ā”€ tests/                       # Test suite (85%+ coverage)
ā”œā”€ā”€ docker/                      # Docker setup
ā”‚   ā”œā”€ā”€ Dockerfile               # Multi-stage production build
ā”‚   ā””ā”€ā”€ docker-compose.yml       # Docker Compose configuration
ā””ā”€ā”€ .github/workflows/           # CI/CD pipelines

Running Tests

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_config.py

# Run with coverage report
uv run pytest --cov=src/kuma_automonitor --cov-report=html

# Run only unit tests
uv run pytest -m unit

# Run with verbose output
uv run pytest -v

Building Docker Image Locally

# Build image
docker build -f docker/Dockerfile -t kuma-automonitor:dev .

# Run image
docker run -d \
  --name kuma-automonitor-dev \
  --env-file .env \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  kuma-automonitor:dev

Docker Development Setup

For development with local builds, use the Docker Compose file in the docker/ directory:

cd docker
docker-compose up -d

This builds the image locally instead of pulling from the registry.

Contributing

Contributions are welcome! Here's how you can help:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes:
    • Follow the existing code style (enforced by ruff)
    • Add tests for new functionality
    • Ensure all tests pass: uv run pytest
    • Update documentation as needed
  4. Commit your changes: git commit -m 'Add amazing feature'
  5. Push to your fork: git push origin feature/amazing-feature
  6. Open a Pull Request

Code Quality Standards

  • Test Coverage: Maintain 85%+ code coverage
  • Linting: Code must pass ruff check and ruff format --check
  • Type Hints: Add type hints to all new functions
  • Documentation: Update README and docstrings for new features

Troubleshooting

Docker Socket Permission Denied

Problem: Permission denied while trying to connect to the Docker daemon socket

Solution: Ensure the Docker socket is mounted and accessible:

# Check Docker socket permissions
ls -l /var/run/docker.sock

# Add user to docker group (Linux)
sudo usermod -aG docker $USER

Kuma Authentication Failed

Problem: Failed to authenticate with Uptime Kuma

Solution:

  • Verify your KUMA_TOKEN is correct and not expired
  • Check that KUMA_URL is accessible from your server
  • If using self-signed certificates, set KUMA_VERIFY_TLS=false

Monitors Not Appearing

Problem: Containers are detected but monitors don't appear in Uptime Kuma

Solution:

  • Check the application logs: docker logs kuma-automonitor
  • Verify the token has permission to create monitors
  • Ensure Uptime Kuma is on a compatible version (v1.x or v2.x)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Uptime Kuma - The excellent open-source monitoring tool that makes this possible
  • uptime-kuma-api - Python API client for Uptime Kuma
  • Docker SDK for Python - For Docker API interactions

Support

  • Issues: GitHub Issues
  • Discussions: GitHub Discussions
  • Documentation: See .env.sample for configuration details

Made with ā¤ļø for the Uptime Kuma community

Ecosystem Role

Standard MoltPulse indexed agent.