[](HEADER)

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:

*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

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:

docker pull ghcr.io/bigboot/autokuma:latest

Dev Version:

docker pull ghcr.io/bigboot/autokuma: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://{{@0}}:{{@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
      
    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:

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

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 might change in the future.

kuma.mydocker.docker_host.name: 'My Docker Host'
kuma.mydocker.docker_host.connection_type: 'socket'
kuma.mydocker.docker_host.path: '/var/run/docker.sock'

kuma.mymonitor.http.name: 'This is a Docker Monitor'
kuma.mymonitor.http.docker_host_name: 'mydocker'
kuma.mymonitor.http.url: 'https://example.com'

Tags

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

kuma.mytag.tag.name: 'A purple label'
kuma.mytag.tag.color: '#FF00FF'

kuma.mymonitor.http.name: 'This is a Monitor with a label'
kuma.mymonitor.http.tag_names: '[{"name": "mytag", "value": "A value (this is optional)" }]'
kuma.mymonitor.http.url: 'https://example.com'

Templating

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

Snippets 📝

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

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

or in an equivalent TOML config file:

[snippets]
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"] }'

!Snippets

There's a special case for snippets starting with a !, these snippets will apply to labels without requiring the prefix (i.e. kuma.__). The purpose of these is to be able to reuse existing labels from other tools. (Note: Due to this !Snippets will always receive a single string argument containing the label value instead of a structured list).

For example you could create a snippet to reuse traefik labels by defining a snippet called !traefik.enable:

{# Only apply if value is "true" #}
{% if args[0] == "true" %}
    {# Extract some information from existing labels, note that this will likely not fit your setup and you will need to adjust this to get the required data #}
    {% set traefik_service = container_name %}
    {% set domain = container_name + ".example.com" %}
    {% set port = container["Labels"]["traefik.http.services." + traefik_service + ".loadbalancer.server.port"] %}

    {{ container_name }}_http.http.name: {{ container_name }}
    {{ container_name }}_http.http.url: https://{{ domain }}:{{ port }}
{% endif %}

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:

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