#docker #monitoring #automation #container-image #uptime-kuma #automate

app autokuma

Automates the creation of Uptime Kuma monitors based on Docker container labels

3 releases (breaking)

0.6.0 Apr 28, 2024
0.5.0 Apr 13, 2024
0.4.1 Apr 2, 2024
0.0.3 Apr 2, 2024

#478 in Command line utilities

Download history 211/week @ 2024-03-28 56/week @ 2024-04-04 134/week @ 2024-04-11 4/week @ 2024-04-18 136/week @ 2024-04-25 15/week @ 2024-05-02 1/week @ 2024-05-16

152 downloads per month

MIT license


AutoKuma Crates.io Version

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.

🔧 How to Install

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:

docker pull ghcr.io/bigboot/autokuma:latest

Example Docker Compose

Here's an example docker-compose.yml:

version: '3'

    image: ghcr.io/bigboot/autokuma:latest
    restart: unless-stopped
      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__TAG_NAME: AutoKuma
      # AUTOKUMA__TAG_COLOR: "#42C0FB"
      #    docker.docker_container: {{container_name}}
      #    http.max_redirects: 10
      #    *.max_retries: 3
      #    {{container_name}}_http.http.name: {{container_name}} HTTP
      #    {{container_name}}_http.http.url: https://{{@0}}:{{@1}}
      #    {{container_name}}_docker.docker.name: {{container_name}} Docker
      #    {{container_name}}_docker.docker.docker_container: {{container_name}}
      # AUTOKUMA__DOCKER__SOCKET: /var/run/docker.sock
      - /var/run/docker.sock:/var/run/docker.sock


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__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__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__SOCKET docker.socket Path to the Docker socket
AUTOKUMA__DOCKER__LABEL_PREFIX docker.label_prefix Prefix used when scanning for container labels

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:

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


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 monitor types and the corresponding settings.

AutoKuma also provides support for creating and assigning groups:

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"

AutoKuma allows the usage of Tera templates in labels and Snippets, the following variables are available:

Template Description Example Value
container_id The container id 92366941fb1f211c573c56d261f3b3e5302f354941f2aa295ae56d5781e97221
image_id Sha256 of the container image sha256:c2e38600b252f147de1df1a5ca7964f9c8e8bace97111e56471a4a431639287a
image Name of the container image ghcr.io/immich-app/immich-server:release
container_name Name of the container immich-immich-1
container Nested structure with container details See the Docker Engine Documentation for the available data


WARNING: Snippets are currently experimental and might change in the future.

AutoKuma provides the ability to define reusable snippets. Snippets need to be defined in the configuration, for example, using environment variables:

    {{ 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 }}

or in an equivalent TOML config file:

web = '''
    {{ container_name }}_http.http.name: {{ container_name }}
    {{ container_name }}_http.http.url: https://{{ args[0] }}:{{ args[1] }}
    {{ container_name }}_docker.docker.name: {{ container_name }}_docker
    {{ container_name }}_docker.docker.docker_name: {{ container_name }}

These define a snippet called web.

A snippet can have a variable number of arguments, which are available as replacements using {{ args[0] }}, {{ args[1] }}, {{ args[2] }}, etc., as seen above.

To use a snippet on a container, assign a label in the format:

<prefix>.__<snippet>: <arguments>

For example, the above snippet could be included using the following label:

kuma.__web: "example.com", 443

Snippets also use Tera, which allows for some quite advanced templates, here's a extended variation of the above example:

{# Assign the first snippet arg to args to make access easier #}
{% set args = args[0] %}

{# Generate an autokuma id by slugifying the "name" arg #}
{% set id = args.name | slugify %}

{# if we have a "keyword" generate a "keyword" monitor, otherwise generate a "http" monitor #}
{% if args.keyword %}
    {% set type = "keyword" %}
{% else %}
    {% set type = "http" %}
{% endif %}

{# below are the actual lines which end up defining the monitor #}
{{ id }}-group.group.name: {{ args.name }}
{{ id }}-http.{{ type }}.name: {{ args.name }} (HTTP)
{{ id }}-http.{{ type }}.parent_name: {{ id }}-group
{{ id }}-http.{{ type }}.url: {{ args.url }}
{% if args.keyword %}
    {{ id }}-http.{{ type }}.keyword: {{ args.keyword }}
{% endif %}
{% if args.status_code %}
    {{ id }}-http.{{ type }}.status_code: {{ args.status_code }}
{% endif %}
{{ id }}-http-container.docker.name: {{ args.name }} (Container)
{{ id }}-http-container.docker.parent_name: {{ id }}-group

And the usage of it would be like the following: Just a basic http monitor:

kuma.__web: '{ "name": "Example HTTP", "url": "https://example.com" }'

Keyword monitor with custom status_codes:

kuma.__web: '{ "name": "Example HTTP", "url": "https://example.com", "keyword": "Example Domain", "status_codes": ["200"] }'

Static Monitors

In addition to reading Monitors from Docker labels, AutoKuma can create Monitors from files. This can be usefull if you have want AutoKuma to manage monitors which aren't directly related to a container.

To create static Monitors just add a .json or .toml file in the directory specified by AUTOKUMA__STATIC_MONITORS, take a look at the examples here.

The default directory for static monitors is:

Platform Value Example
Linux $XDG_CONFIG_HOME/autokuma/static-monitors/ /home/alice/.config/autokuma/static-monitors/
macOS $HOME/Library/Application Support/autokuma/static-monitors/ /Users/Alice/Library/Application Support/autokuma/static-monitors/
Windows %LocalAppData%\\autokuma\\static-monitors\\ C:\\Users\\Alice\\AppData\\Local\\autokuma\\static-monitors\\

In case of static Monitors the id is determined by the filename (without the extension).


~870K SLoC