<img src="https://github.com/BigBoot/AutoKuma/raw/v2.0.0/logo.svg" height="196" alt="" />

    <a href="https://github.com/BigBoot/AutoKuma/actions"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/BigBoot/AutoKuma/docker-build-push.yml?style=flat&logo=rust&link=https%3A%2F%2Fgithub.com%2FBigBoot%2FAutoKuma%2Factions"></a>
    <a href="https://github.com/BigBoot/AutoKuma/releases/latest"><img alt="GitHub Tag" src="https://img.shields.io/github/v/tag/BigBoot/AutoKuma?logo=github&label=latest"></a>
    <a href="https://ghcr.io/bigboot/autokuma"><img alt="GHCR Tag" src="https://img.shields.io/github/v/tag/BigBoot/AutoKuma?logo=docker&logoColor=white&label=GHCR"></a>






    <b>
        <a href="#autokuma--">AutoKuma</a>
        &nbsp&nbsp
        <a href="#kuma-cli---">Kuma CLI</a> 
        &nbsp&nbsp
        <a href="#kuma-client--">Kuma Client</a> 
    </b>

AutoKuma 🐻

AutoKuma is a utility that automates the creation of Uptime Kuma monitors based on Docker container labels. With AutoKuma, you can eliminate the need for manual monitor creation in the Uptime Kuma UI.

Supported sources

AutoKuma initially supported sourcing monitor configurations from docker labels, over the time a few other methods were added, here is an overview of the available sources:

Source	Description	Support
Docker	Monitors are sourced from container labels	✅
Files	Monitors are sourced from .json/.toml files	✅
Docker Swarm	Monitors can be sourced from service and/or container labels	⚠️*
Kubernetes	Monitors are sourced from CR, see the CRDs in autokuma/kubernetes/crds-autokuma.yml. Additionally the Files and Docker provider might be used depending on your setup	⚠️*

*These sources are supported on an as-is basis as I'm currently not running any of them (They are basically looking for a maintainer, please get in contact if you'd like to adopt one or add support for another source).

How to Install 📦

Supported Platforms

Platform	Architecture	Docker Images	Prebuild Binaries	Notes
Windows	x64	⛔︎	✅
Windows	arm64	⛔︎	⛔︎
Linux	x64	✅	✅*
Linux	arm64	⚠️*	⛔︎	Experimental
Mac	x64	⛔︎	⛔︎
Mac	arm64	⛔︎	⚠️*	Experimental

Binaries for windows linux and mac are provided for GitHub Releases, additionally AutoKuma is available as a Docker container on GitHub Container Registry (GHCR). To install, simply pull the container using:

Latest Release:

# For Uptime Kuma V2
docker pull ghcr.io/bigboot/autokuma:latest
# For Uptime Kuma V1
docker pull ghcr.io/bigboot/autokuma:uptime-kuma-v1-latest

Dev Version:

# For Uptime Kuma V2
docker pull ghcr.io/bigboot/autokuma:master
# For Uptime Kuma V1
docker pull ghcr.io/bigboot/autokuma:uptime-kuma-v1-master

❗ The dev version might break or contain breaking changes without warning, usage on a production system is not adviced.

Example Docker Compose 🚀

Here's an example docker-compose.yml:

version: '3'

services:
  autokuma:
    image: ghcr.io/bigboot/autokuma:latest
    restart: unless-stopped
    environment:
      AUTOKUMA__KUMA__URL: http://localhost:3001
      # AUTOKUMA__KUMA__USERNAME: <username> 
      # AUTOKUMA__KUMA__PASSWORD: <password>
      # AUTOKUMA__KUMA__MFA_TOKEN: <token>
      # AUTOKUMA__KUMA__HEADERS: "<header1_key>=<header1_value>,<header2_key>=<header2_value>,..."
      # AUTOKUMA__KUMA__CALL_TIMEOUT: 5
      # AUTOKUMA__KUMA__CONNECT_TIMEOUT: 5
      # AUTOKUMA__TAG_NAME: AutoKuma
      # AUTOKUMA__TAG_COLOR: "#42C0FB"
      # AUTOKUMA__DEFAULT_SETTINGS: |- 
      #    docker.docker_container: {{container_name}}
      #    http.max_redirects: 10
      #    *.max_retries: 3
      # AUTOKUMA__SNIPPETS__WEB: |- 
      #    {{container_name}}_http.http.name: {{container_name}} HTTP
      #    {{container_name}}_http.http.url: https://{{ args[0] }}:{{ args[1] }}
      #    {{container_name}}_docker.docker.name: {{container_name}} Docker
      #    {{container_name}}_docker.docker.docker_container: {{container_name}}
      # AUTOKUMA__DOCKER__HOSTS: unix:///var/run/docker.sock
      # AUTOKUMA__DOCKER__LABEL_PREFIX: kuma
      # AUTOKUMA__DOCKER__EXCLUDE_CONTAINER_PATTERNS: "^[a-f0-9]{12}_.*_"  # Exclude Docker Compose temporary containers

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - autokuma-data:/data

volumes:
  autokuma-data:

Configuration 🔧

AutoKuma can be configured using the following environment variables/config keys:

Env Variable	Config Key	Description
AUTOKUMA__STATIC_MONITORS	static_monitors	The path to the folder in which AutoKuma will search for static Monitor definitions
AUTOKUMA__TAG_NAME	tag_name	The name of the AutoKuma tag, used to track managed containers
AUTOKUMA__TAG_COLOR	tag_color	The color of the AutoKuma tag
AUTOKUMA__DEFAULT_SETTINGS	default_settings	Default settings applied to all generated Monitors, see the example above for the syntax
AUTOKUMA__LOG_DIR	log_dir	Path to a directory where log files will be stored
AUTOKUMA__ON_DELETE	on_delete	Specify what should happen to a monitor if the autokuma id is not found anymore, either delete or keep
AUTOKUMA__DELETE_GRACE_PERIOD	delete_grace_period	How long to wait in seconds before deleting the entity if the autokuma is not not found anymore
AUTOKUMA__INSECURE_ENV_ACCESS	insecure_env_access	Allow access to all env variables in templates, by default only variables starting with AUTOKUMA__ENV__ can be accessed.
AUTOKUMA__SNIPPETS__<SNIPPET>	snippets.<snippet>	Define a snippet named <snippet>, see Snippets for details
AUTOKUMA__KUMA__URL	kuma.url	The URL AutoKuma should use to connect to Uptime Kuma
AUTOKUMA__KUMA__USERNAME	kuma.username	The username for logging into Uptime Kuma (required unless auth is disabled)
AUTOKUMA__KUMA__PASSWORD	kuma.password	The password for logging into Uptime Kuma (required unless auth is disabled)
AUTOKUMA__KUMA__MFA_TOKEN	kuma.mfa_token	The MFA token for logging into Uptime Kuma (required if MFA is enabled)
AUTOKUMA__KUMA__MFA_SECRET	kuma.mfa_secret	The MFA secret. Used to generate a tokens for logging into Uptime Kuma (alternative to a single_use mfa_token)
AUTOKUMA__KUMA__HEADERS	kuma.headers	List of HTTP headers to send when connecting to Uptime Kuma
AUTOKUMA__KUMA__CONNECT_TIMEOUT	kuma.connect_timeout	The timeout for the initial connection to Uptime Kuma
AUTOKUMA__KUMA__CALL_TIMEOUT	kuma.call_timeout	The timeout for executing calls to the Uptime Kuma server
AUTOKUMA__DOCKER__HOSTS	docker.hosts	List of Docker hosts. Use a semicolon separated string when setting using an env variable.
AUTOKUMA__DOCKER__LABEL_PREFIX	docker.label_prefix	Prefix used when scanning for container labels
AUTOKUMA__DOCKER__SOURCE	docker.source	Whether monitors should be created from Containers or Services labels (or Both).
AUTOKUMA__DOCKER__EXCLUDE_CONTAINER_PATTERNS	docker.exclude_container_patterns	Regex patterns to exclude containers by name (semicolon-separated)
AUTOKUMA__DOCKER__TLS__VERIFY	docker.tls.verify	Whether to verify the TLS certificate or not.
AUTOKUMA__DOCKER__TLS__CERT	docker.tls.cert	The path to a custom tls certificate in PEM format.
AUTOKUMA__FILES__FOLLOW_SYMLINKS	files.follow_symlinks	Whether AutoKuma should follow symlinks when looking for "static monitors" (Defaults to false)

AutoKuma will read configuration from a file named autokuma.{toml,yaml,json} in the current directory and in the following locations:

Platform	Value	Example
Linux	$XDG_CONFIG_HOME/autokuma/config.{toml,yaml,json}	/home/alice/.config/autokuma/config.toml
macOS	$HOME/Library/Application Support/autokuma/config.{toml,yaml,json}	/Users/Alice/Library/Application Support/autokuma/config.toml
Windows	%LocalAppData%\autokuma\config.{toml,yaml,json}	C:\Users\Alice\AppData\Local\autokuma\config.toml

An example .toml config could look like the following:

[kuma]
url = "http://localhost:3001/"
username = "<username>"
password = "<password>"

Usage 💡

AutoKuma interprets Docker container labels with the following format:

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

• <prefix>: Default is kuma unless changed using the DOCKER__LABEL_PREFIX env variable.
• <id>: A unique identifier for the monitor (ensure it's unique between all monitors).
• <type>: The type of the monitor as configured in Uptime Kuma.
• <setting>: The key of the value to be set.
• <value>: The value for the option.

Labels are grouped by <id> into a single monitor. For example, to create a simple HTTP monitor, use the following labels:

kuma.example.http.name: "Example"
kuma.example.http.url: "https://example.com"

Take a look at all available entity types and their corresponding settings.

Groups

To assign a monitor to a group set it's parent_name property to the autokuma id of the group, e.g.

kuma.mygroup.group.name: 'This is a Group'

kuma.mymonitor.http.name: 'This is a Monitor assigned to a Group'
kuma.mymonitor.http.parent_name: 'mygroup'
kuma.mymonitor.http.url: 'https://example.com'

Notifications

WARNING: Defining Notifications is currently experimental and might change in the future.

kuma.mynotificationprovider.notification.name: 'This is a Matrix notification provider'
kuma.mynotificationprovider.notification.active: 'true'
kuma.mynotificationprovider.notification.config: '{"type": "matrix", "accessToken": "XXXXXXXXXXXXXXXXXX", "homeserverUrl": "https://matrix.org", "internalRoomId": "!xxxxxxxxxxxxxxxxxx:matrix.org"}'

kuma.mymonitor.http.name: 'This is a Monitor with a notification provider'
kuma.mymonitor.http.notification_names: '["mynotificationprovider"]'
kuma.mymonitor.http.url: 'https://example.com'

Docker Hosts

WARNING: Defining Docker Hosts is currently experimental and