infrastructure/docs/13-DOCKERPROXY-NETWORK.md

# dockerproxy Docker Network

User-defined Docker bridge on Unraid hosting Traefik and all reverse-proxied services. Defined imperatively (not in any compose file — stacks reference it as `external: true`).

## IPAM

| Property | Value |
|----------|-------|
| Driver | `bridge` |
| Subnet | `172.18.0.0/16` |
| Gateway | `172.18.0.1` |
| IP Range (dynamic pool) | `172.18.0.128/25` (.128–.255) |
| Static reservation block | `172.18.0.2 – 172.18.0.127` |

The `--ip-range` constrains Docker's auto-allocation to `.128–.255`. Anything pinned via compose `ipv4_address` outside that range is conflict-free. Set up 2026-05-17 after the collision incident in `incidents/2026-05-17-traefik-ip-collision.md`.

## Recreate Command

If the network is ever lost (Docker reset, accidental `docker network rm`):

```bash
docker network create \
  --driver bridge \
  --subnet 172.18.0.0/16 \
  --gateway 172.18.0.1 \
  --ip-range 172.18.0.128/25 \
  dockerproxy
```

After recreating, compose-managed containers reconnect via `docker compose up -d`. Standalone containers need `docker network connect [--ip <static>] dockerproxy <name>`.

## Static Assignments (2026-05-17)

| IP | Container |
|----|-----------|
| .1 | (gateway) |
| .3 | traefik |
| .4 | traefik-manager |
| .6 | dockersocket |
| .8 | authentik-worker |
| .9 | authentik |
| .10 | postgresql17 |
| .14 | Redis |
| .15 | vaultwarden |
| .16 | actual-budget |
| .18 | Uptime-Kuma-API |
| .19 | AutoKuma |
| .20 | UptimeKuma |
| .21 | speedtest-tracker |
| .22 | obsidian-livesync |
| .23 | SeekAndWatch |
| .25 | karakeep |
| .26 | transmission |
| .31 | gitea |
| .32 | woodpecker-server |
| .33 | woodpecker-agent |
| .43 | radarr |
| .44 | sonarr |
| .45 | prowlarr |
| .50 | dockhand |
| .53 | n8n |
| .60 | overseerr |
| .61 | plex_debrid |
| .62 | zurg |
| .63 | zurg-rclone |
| .65 | xtrm-agent |
| .66 | kasm |
| .70 | ewa-apps |
| .128+ | dynamic pool (traefik-manager landed here) |

## Adding a New Service

1. Pick a free IP in `.2–.127` (or omit and accept dynamic `.128+`)
2. In compose:
   ```yaml
   services:
     myservice:
       networks:
         dockerproxy:
           ipv4_address: 172.18.0.X
   networks:
     dockerproxy:
       external: true
   ```
3. Append to the table above and commit.

## Snapshot of Pre-Recreate State

On Unraid: `/root/dockerproxy-recreate-2026-05-17/`
- `network-before.json` — full `docker network inspect` output
- `state.tsv` — per-container name/static-IP/runtime-IP/status/restart-policy
- `containers.txt` — sorted container list (32 entries)

## Monitoring

Two Uptime Kuma monitors cover Traefik (since 2026-05-17):

| 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:
- #6 red + #39 green → Traefik is up but misconfigured/routing-broken
- both red → Traefik container itself is down

## AutoKuma Setup (v2)

AutoKuma reads Docker container labels and creates monitors in Uptime Kuma. Required env vars in `/mnt/user/appdata/dockge/stacks/uptime-kuma/compose.yaml`:

```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.