autokuma

Crates.ioautokuma
lib.rsautokuma
version0.5.0
sourcesrc
created_at2024-04-02 16:16:01.30226
updated_at2024-04-13 09:49:22.416768
descriptionAutomates the creation of Uptime Kuma monitors based on Docker container labels
homepage
repositoryhttps://github.com/BigBoot/AutoKuma
max_upload_size
id1193696
size109,027
(BigBoot)

documentation

README

Error: No matches. # 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](https://github.com/BigBoot/AutoKuma/releases/latest), additionally AutoKuma is available as a Docker container on [GitHub Container Registry (GHCR)](https://github.com/BigBoot/AutoKuma/pkgs/container/autokuma). To install, simply pull the container using: ```bash docker pull ghcr.io/bigboot/autokuma:latest ``` ## Example Docker Compose Here's an example `docker-compose.yml`: ```yaml version: '3' services: autokuma: image: ghcr.io/bigboot/autokuma:latest restart: unless-stopped environment: AUTOKUMA__KUMA__URL: http://localhost:3001 # AUTOKUMA__KUMA__USERNAME: # AUTOKUMA__KUMA__PASSWORD: # AUTOKUMA__KUMA__MFA_TOKEN: # AUTOKUMA__KUMA__HEADERS: "=,=,..." # 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__SOCKET: /var/run/docker.sock # AUTOKUMA__DOCKER__LABEL_PREFIX: kuma volumes: - /var/run/docker.sock:/var/run/docker.sock ``` ## 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__SNIPPETS__` | `snippets.` | Define a snippet named ``, see [Snippets](#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: ```toml [kuma] url = "http://localhost:3001/" username = "" password = "" ``` ## Usage AutoKuma interprets Docker container labels with the following format: ```plaintext ...: ``` - ``: Default is `kuma` unless changed using the `DOCKER__LABEL_PREFIX` env variable. - ``: A unique identifier for the monitor (ensure it's unique between all monitors). - ``: The type of the monitor as configured in Uptime Kuma. - ``: The key of the value to be set. - ``: The value for the option. Labels are grouped by `` into a single monitor. For example, to create a simple HTTP monitor, use the following labels: ```plaintext kuma.example.http.name: "Example" kuma.example.http.url: "https://example.com" ``` Take a look at [all available monitor types](MONITOR_TYPES.md) and the corresponding settings. AutoKuma also provides support for creating and assigning groups: ```plaintext 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" ``` There are also some text replacements available which will be replaced by details about the corresponding docker container: | 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 | ### Snippets **_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: ```yaml 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}} ``` or in an equivalent TOML config file: ```toml [snippets] web = ''' {{container_name}}_http.http.name: {{container_name}} {{container_name}}_http.http.url: https://{{@0}}:{{@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 `{{@0}}`, `{{@1}}`, `{{@2}}`, etc., as seen above. To use a snippet on a container, assign a label in the format: ```plaintext .__: ``` For example, the above snippet could be included using the following label: ```plaintext kuma.__web: "example.com", 443 ``` ### 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](monitors). 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).
Commit count: 65

cargo fmt