From 08874ca0b3a5e020d046eb6f5008961053a9c57a Mon Sep 17 00:00:00 2001
From: jazzymc <kaloyan.danchev@ampeco.global>
Date: Mon, 18 May 2026 12:45:19 +0300
Subject: [PATCH] autokuma: fix v1->v2 config and label syntax
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Replace v1 AUTOKUMA_DOCKER=1 with v2 env vars (ENABLED, HOSTS, SOURCE)
- Rewrite traefik-manager labels in v2 4-part syntax: kuma.<id>.<type>.<setting>
- Delete manually-created monitor #38; AutoKuma recreates it (now #39) cleanly
- Document v2 label requirements and the remaining v1-label migration

Default AUTOKUMA__DOCKER__SOURCE is Swarm Services — must be set to
Containers for standalone Docker. v2 also doesn't accept the v1 shorthand
(kuma=URL + kuma.name=... + kuma.type=...), only the explicit 4-part form.
---
 docs/13-DOCKERPROXY-NETWORK.md | 62 +++++++++++++++++++++++++++++-----
 1 file changed, 54 insertions(+), 8 deletions(-)

diff --git a/docs/13-DOCKERPROXY-NETWORK.md b/docs/13-DOCKERPROXY-NETWORK.md
index 0c60971..8eefe41 100644
--- a/docs/13-DOCKERPROXY-NETWORK.md
+++ b/docs/13-DOCKERPROXY-NETWORK.md
@@ -95,17 +95,63 @@ On Unraid: `/root/dockerproxy-recreate-2026-05-17/`
 
 Two Uptime Kuma monitors cover Traefik (since 2026-05-17):
 
-| ID | Name | Type | Target | Purpose |
-|----|------|------|--------|---------|
-| 6 | Traefik Dashboard | http | https://traefik.xtrm-lab.org | End-to-end check (routing + TLS) |
-| 38 | Traefik Container (direct) | port | tcp://172.18.0.3:80 | Direct TCP probe inside dockerproxy — detects "container not running" independently of routing |
+| ID | Name | Type | Target | Managed by | Purpose |
+|----|------|------|--------|------------|---------|
+| 6 | Traefik Dashboard | http | https://traefik.xtrm-lab.org | manual | End-to-end check (routing + TLS) |
+| 39 | Traefik Container (direct) | port | tcp://172.18.0.3:80 | AutoKuma | Direct TCP probe inside dockerproxy — detects "container not running" independently of routing |
 
 Diagnostic combination:
-- id=6 red + id=38 green → Traefik is up but misconfigured/routing-broken
+- #6 red + #39 green → Traefik is up but misconfigured/routing-broken
 - both red → Traefik container itself is down
 
-## Known Issue — AutoKuma broken
+## AutoKuma Setup (v2)
 
-AutoKuma v2.0.0 logs into Uptime Kuma successfully but silently loops on `getTags` and never scans Docker containers. Suspected `AUTOKUMA_DOCKER=1` (single-underscore v1 syntax) isn't recognised by v2's nested-double-underscore config. Also, the bundled `medaziz11/uptimekuma_restapi:dev` API container is out of date — its `POST /monitors` fails on the now-required `conditions` column.
+AutoKuma reads Docker container labels and creates monitors in Uptime Kuma. Required env vars in `/mnt/user/appdata/dockge/stacks/uptime-kuma/compose.yaml`:
 
-As a workaround, monitor id=38 was created with a direct `INSERT INTO monitor` on `/mnt/user/appdata/uptimekuma/kuma.db` followed by an UK container restart. The `kuma.traefik_container.*` labels on `traefik-manager` are inert until AutoKuma is fixed but kept in place for that future.
+```yaml
+- "AUTOKUMA__KUMA__URL=http://172.18.0.20:3001"
+- "AUTOKUMA__KUMA__USERNAME=admin"
+- "AUTOKUMA__KUMA__PASSWORD=..."
+- "AUTOKUMA__TAG_NAME=AutoKuma"
+- "AUTOKUMA__TAG_COLOR=#42C0FB"
+- "AUTOKUMA__DOCKER__ENABLED=true"           # v2 syntax — v1's AUTOKUMA_DOCKER=1 is ignored
+- "AUTOKUMA__DOCKER__HOSTS=unix:///var/run/docker.sock"
+- "AUTOKUMA__DOCKER__SOURCE=Containers"      # default is Swarm Services — wrong for standalone Docker
+```
+
+### Label syntax (v2)
+
+v2 requires **4-part labels**: `kuma.<id>.<type>.<setting>`. v1 shorthand (`kuma=...` + `kuma.name=...` + `kuma.type=...`) is silently ignored.
+
+```yaml
+# HTTP monitor
+- "kuma.dockhand.http.name=Dockhand"
+- "kuma.dockhand.http.url=https://dockhand.xtrm-lab.org"
+
+# TCP port monitor
+- "kuma.traefik_container.port.name=Traefik Container (direct)"
+- "kuma.traefik_container.port.hostname=172.18.0.3"
+- "kuma.traefik_container.port.port=80"
+- "kuma.traefik_container.port.interval=30"
+```
+
+AutoKuma is idempotent on restart — it tracks its own monitors in its internal sled DB (in-container), not via UK tags as in v1. The `tag` table in `kuma.db` can stay empty.
+
+### Legacy v1 labels — open follow-up
+
+The following containers still carry **v1 shorthand labels** that v2 ignores. Their corresponding UK monitors continue to work but are now manual, not AutoKuma-managed:
+
+| Container | UK monitor (manual) |
+|-----------|---------------------|
+| traefik | #6 Traefik Dashboard |
+| dockhand | (no monitor) |
+| xtrm-agent | (no monitor) |
+| rustdesk-hbbs | (no monitor) |
+| rustdesk-hbbr | (no monitor) |
+| Nextcloud (stopped) | #14 Nextcloud |
+
+Migration is per-container: rewrite labels to v2 4-part syntax (in compose / Unraid template), delete the corresponding existing monitor, let AutoKuma recreate cleanly.
+
+## Known Issues
+
+- `medaziz11/uptimekuma_restapi:dev` is **stale relative to UK 2.3** — its `POST /monitors` fails because the new `conditions` column is NOT NULL and the API doesn't pass it. Workaround: direct SQL insert on `kuma.db` and restart UK. Replace the API container with a current image at some point.