DOCSEARCHbyAlgolia
Submit Docs

AutoKuma Documentation

repository·master·Indexed 21 days ago

https://github.com/bigboot/autokuma

AutoKuma is a utility that automates the creation of Uptime Kuma monitors using Docker container labels. It includes a CLI for terminal-based management of monitors, tags, notifications, and status pages, as well as the kuma-client Rust crate for interacting with the Uptime Kuma SocketIO API. The project also features a Playground engine for validating docker-compose files, testing configuration, and developing Tera templates for monitor snippets.

Tokens
62.3K
Snippets
169
Records
243
Agent score
75%

What's inside AutoKuma

  1. Overview of AutoKuma components

    master

    AutoKuma is a utility designed to automate the creation and synchronization of Uptime Kuma monitors. It works by watching infrastructure sources (like Docker labels or files) and ensuring Uptime Kuma reflects those sources. If a source is added, a monitor is created; if a source is removed, the monitor is deleted.

    The project consists of three primary components:

    1. AutoKuma: The main daemon responsible for syncing monitors from various sources.
    2. Kuma CLI: A command-line interface for direct management of Uptime Kuma.
    3. Kuma Client: A Rust library for interacting with the Uptime Kuma SocketIO API.

  2. What is AutoKuma and how does it work?

    master

    AutoKuma is a daemon designed to synchronize Uptime Kuma monitors with your infrastructure. It automates monitor management by scanning configured sources for monitor definitions.

    Core Workflow:

    1. Scanning: AutoKuma periodically scans sources such as Docker container labels, static files, Docker Swarm services, or Kubernetes resources.
    2. Identification: Each monitor definition must have a unique AutoKuma ID. AutoKuma uses this ID to track managed monitors via a specific Uptime Kuma tag.
    3. Synchronization: AutoKuma ensures the monitors in Uptime Kuma match the definitions found in your infrastructure. If a definition is removed from a source, AutoKuma can either delete the corresponding monitor in Uptime Kuma or keep it, based on your configuration settings.

  3. Use the `real-browser` monitor type

    master

    The real-browser monitor is a headless browser monitor that uses a remote Chrome instance to load a page and verify successful rendering. It is useful for checking if complex, JavaScript-heavy pages render correctly rather than just checking HTTP status codes.

    labels:
  kuma.browser.real-browser.name: "Browser Check"
  kuma.browser.real-browser.url: "https://example.com"
  kuma.browser.real-browser.remote_browser: "ws://chrome:3000"

  4. Configure a `dns` monitor

    master

    The dns entity type is a DNS resolution monitor. It verifies that a specific hostname resolves to an expected value using a designated DNS server. You can configure the resolution type (e.g., A record), the server to query, and the check interval.

    labels:
  kuma.my-dns.dns.name: "DNS Check"
  kuma.my-dns.dns.hostname: "example.com"
  kuma.my-dns.dns.dns_resolve_server: "1.1.1.1"
  kuma.my-dns.dns.dns_resolve_type: "A"
  kuma.my-dns.dns.interval: "60"

  5. Format Docker container labels for AutoKuma

    master

    AutoKuma uses Docker container labels to automatically create monitors in Uptime Kuma. Labels must follow a specific hierarchical format. Labels that share the same <id> are merged into a single monitor definition.

    Label Format: <prefix>.<id>.<type>.<setting>: <value>

    • <prefix>: The default is kuma. You can change this by setting the environment variable AUTOKUMA__DOCKER__LABEL_PREFIX.
    • <id>: A unique identifier for the monitor. This must be unique across all monitors.
    • <type>: The monitor type as configured in Uptime Kuma (e.g., http, ping, dns, docker).
    • <setting>: The property name to set.
    • <value>: The value for the setting.
    labels:
  kuma.example.http.name: "Example"
  kuma.example.http.url: "https://example.com"

  6. Configure an MQTT broker monitor

    master

    The mqtt entity type is used to monitor an MQTT broker by subscribing to a specific topic and verifying if an expected message or keyword is present.

    There are two primary modes of operation defined by mqtt_check_type:

    1. keyword: Checks if the message contains a specific string.
    2. json-query: Uses a json_path to extract a value from a JSON message and compares it against an expected_value using a json_path_operator.

    Common configuration properties include:

    • mqtt_topic: The topic to subscribe to.
    • hostname and port: Connection details for the broker.
    • mqtt_username and mqtt_password: Authentication credentials.
    • mqtt_success_message: The string expected for a successful check (used in keyword mode).
    • json_path and json_path_operator: Used for extracting and comparing values in json-query mode.
    • interval: How often to perform the check in seconds.
    labels:
  kuma.mqtt-sensor.mqtt.name: "Sensor Status"
  kuma.mqtt-sensor.mqtt.hostname: "mqtt.example.com"
  kuma.mqtt-sensor.mqtt.mqtt_topic: "sensors/status"
  kuma.mqtt-sensor.mqtt.mqtt_success_message: "online"

  7. Use the `push` monitor type for heartbeat monitoring

    master

    The push monitor (also known as a heartbeat monitor) is used when your service needs to notify AutoKuma of its health by calling a unique URL at regular intervals. If the specific push URL is not called within the configured interval, the monitor is marked as down.

    Key Properties

    PropertyTypeDescription
    push_tokenstringA unique, auto-generated token used to construct the heartbeat URL.
    intervalintegerThe expected heartbeat interval in seconds.
    accepted_statuscodesstringA range of HTTP status codes (e.g., 200-299) that indicate a successful heartbeat.
    activebooleanWhether the monitor is currently active.
    upside_downbooleanIf true, the status is inverted (e.g., a missing heartbeat would be considered
    labels:
  kuma.my-cron.push.name: "Nightly Backup"
  kuma.my-cron.push.interval: "86400"

  8. Configure an `http` monitor

    master

    The http monitor type is used to fetch a URL and verify its response status code. It is the most common monitor type in AutoKuma. You can configure various properties including authentication methods, request headers, body encoding, and retry logic.

    labels:
  kuma.my-site.http.name: "My Website"
  kuma.my-site.http.url: "https://example.com"
  kuma.my-site.http.interval: "60"
  kuma.my-site.http.max_retries: "3"

  9. Configure the MongoDB connection health monitor

    master
    The mongodb entity type is a connection health monitor that connects to a MongoDB instance and executes a specific command to verify availability. It uses a JSON path to extract a value from the command result and compares it against an expected_value to determine health status.

  10. Configure a `keyword` HTTP monitor

    master

    A keyword monitor is an HTTP monitor used to check for the presence (or absence) of a specific string within an HTTP response body.

    Key configuration options include:

    • keyword: The string to search for in the response body.
    • invert_keyword: If set to true, the monitor will fail if the keyword is found (instead of passing).
    • url: The endpoint to monitor.
    • method: The HTTP method to use (e.g., GET, POST).
    • accepted_statuscodes: A range of HTTP status codes that are considered successful (e.g., 200-299).
    • interval: How often to perform the check in seconds.
    • upside_down: Inverts the status of the monitor.

    You can also configure authentication (Basic, OAuth, NTLM), TLS settings (client certificates, custom CA), and custom headers.

    labels:
  kuma.my-app.keyword.name: "My App Keyword Check"
  kuma.my-app.keyword.url: "https://example.com"
  kuma.my-app.keyword.keyword: "Welcome"

  11. Use Tera templates in AutoKuma labels

    master

    AutoKuma uses Tera templates within label values to build monitor definitions dynamically from container metadata. You can use these templates to reference container names, IDs, or specific labels to construct URLs, monitor names, and other configuration values. You can test your templates interactively in the AutoKuma Playground.

    labels:
  kuma.{{container_name}}.http.name: "{{container_name}}"
  kuma.{{container_name}}.http.url: "http://{{container_name}}:8080"

  12. Supported monitor sources in AutoKuma

    master

    AutoKuma can automatically discover and manage monitors from the following sources:

    SourceDescriptionSupport Level
    DockerMonitors are sourced from container labelsStable
    FilesMonitors are sourced from .json or .toml filesStable
    Docker SwarmMonitors from service and container labelsCommunity
    KubernetesMonitors from custom resources, files, or Docker labelsCommunity