Bootstrap Homelab-Docs wiki

Initial documentation of the hubris Proxmox homelab as a cross-linked markdown wiki. Per-node pages, cross-cutting infrastructure pages, an investigation log, and an operations cheatsheet. Each node and topic ends with a Changelog section so changes can be tracked in-place going forward. Refreshed against live state on 2026-04-28 — 14 active LXCs (109 syncthing currently stopped) + 1 VM (108 haos). Reflects post-A/B-test state of the 2026-04-21 hubris crash-loop investigation.
2026-04-28 22:53:09 +02:00
commit f5cd320433
31 changed files with 2157 additions and 0 deletions
--- a/containers/101-jellyfin.md
+++ b/containers/101-jellyfin.md
@@ -0,0 +1,34 @@
+# 101 — `jellyfin`
+
+Media server: serves the movies / TV / anime / music / audiobooks / podcasts libraries from `/mnt/library` to LAN clients.
+
+## At a glance
+- **Hostname:** `jellyfin`
+- **IP:** `192.168.8.206`
+- **Privilege:** **unprivileged** + idmap (so it can write to the `media` group on `/mnt/library`)
+- **Resources:** 2 cores / 4 GiB RAM / 16 GiB rootfs
+- **Mounts:** `/mnt/library` ↔ `/mnt/library`
+- **Public hostname:** [`media.hubris.network`](../infrastructure/dns.md) → [caddy](121-caddy.md) → `:8096`
+
+## Service / port map
+
+| Service  | Listen | Notes |
+| -------- | ------ | ----- |
+| jellyfin | `:8096` | HTTP (caddy terminates TLS) |
+
+## Permissions
+Member of the [media GID 10000](../infrastructure/media-permissions.md) standard. Service user `jellyfin` is in the `media` group inside the container; idmap block in `/etc/pve/lxc/101.conf` maps in-container GID 10000 to host GID 10000.
+
+## Related
+- [Caddy reverse proxy](121-caddy.md)
+- [Media permissions](../infrastructure/media-permissions.md)
+- [arriman](122-arriman.md) — \*arr stack writes the libraries jellyfin reads
+- [DNS split-horizon](../infrastructure/dns.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation. No config changes.
+
+### 2026-04-20 — joined the `media` GID 10000 standard
+Idmap block applied; in-container `media` group at GID 10000 mapped to host GID 10000. See [media permissions](../infrastructure/media-permissions.md). Config backup: `/root/101.conf.bak.*`.
--- a/containers/103-paperless.md
+++ b/containers/103-paperless.md
@@ -0,0 +1,41 @@
+# 103 — `paperless`
+
+Paperless-ngx for document management. Ingests scans / PDFs from `/mnt/library/documents` and serves OCR'd indexed copies.
+
+## At a glance
+- **Hostname:** `paperless`
+- **IP:** `192.168.8.130`
+- **Privilege:** privileged
+- **Resources:** 2 cores / 3 GiB RAM / 8 GiB rootfs
+- **Mounts:** `/mnt/library` ↔ `/mnt/library` (consumes `documents/`)
+- **Public hostname:** [`paperless.hubris.network`](../infrastructure/dns.md) → [caddy](121-caddy.md) → `:8000`
+
+## Service / port map
+
+| Service             | Listen  | Notes                            |
+| ------------------- | ------- | -------------------------------- |
+| paperless-webserver | `:8000` | HTTP                             |
+| paperless-task-queue, paperless-scheduler, paperless-consumer | — | systemd workers |
+
+## Auth
+Behind [Authentik forward-auth](124-authentik.md). API path `/api/*` bypasses forward-auth (mobile clients can't follow the browser login redirect; bearer token still enforces auth on `/api`). Header propagation: `PAPERLESS_ENABLE_HTTP_REMOTE_USER=true` and `PAPERLESS_HTTP_REMOTE_USER_HEADER_NAME=HTTP_X_AUTHENTIK_USERNAME` in `/opt/paperless/paperless.conf`. Django auto-creates matching users on first SSO login.
+
+## Storage
+- Documents at `/mnt/library/documents` (owner `www-data:www-data`, mode 750 — *not* on the `media` group, by design).
+
+## Known issues
+- Disk usage was 86.9% at last claudio-monitor reading on 2026-04-21. Monitor or grow rootfs.
+
+## Related
+- [Authentik](124-authentik.md)
+- [Caddy](121-caddy.md)
+- [DNS](../infrastructure/dns.md)
+- [Monitoring](../infrastructure/monitoring.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation.
+
+### 2026-04-21 — wired into Authentik forward-auth
+Cookie-domain-level proxy provider, embedded outpost binding. `/api/*` bypass added in Caddy site block to keep mobile clients working.
--- a/containers/104-gitea.md
+++ b/containers/104-gitea.md
@@ -0,0 +1,58 @@
+# 104 — `gitea`
+
+Self-hosted git server. Source of truth for all `dtoro/*` repositories that auto-deploy across the lab.
+
+## At a glance
+- **Hostname:** `gitea`
+- **IP:** `192.168.8.121`
+- **Privilege:** privileged
+- **Resources:** 1 core / 1 GiB RAM / 8 GiB rootfs
+- **Mounts:** `/mnt/library` ↔ `/mnt/library` (under `/mnt/library/repos`, owner UID 102 / GID 105 — don't touch from other containers)
+- **Public hostname:** [`git.hubris.network`](../infrastructure/dns.md) → [caddy](121-caddy.md) → `:3000`
+- **Version:** 1.25.4 (last verified)
+
+## Service / port map
+
+| Service | Listen   | Notes                          |
+| ------- | -------- | ------------------------------ |
+| gitea   | `:3000`  | HTTP web + git over HTTP       |
+| gitea SSH | `:22`  | git over SSH                   |
+| `gitea-deploy-webhook` | `127.0.0.1:9797` | Receives push events for the customizations repo |
+
+## Customizations
+`/var/lib/gitea/custom` is a checkout of [`dtoro/gitea-customizations`](https://git.hubris.network/dtoro/gitea-customizations).
+- `templates/custom/footer.tmpl` injects:
+  - **Online3DViewer** v0.18.0 (vendored under `public/assets/o3dv/`) for inline 3D preview of CAD raw-file links: 3dm, 3ds, 3mf, amf, bim, brep, dae, fbx, fcstd, glb, gltf, ifc, igs, iges, stp, step, stl, obj, off, ply, wrl.
+  - **PlantUML client JS** (vanilla, vendored from `gitea.com/davidsvantesson/plantuml-code-highlight`). Browser calls `https://git.hubris.network/_plantuml/img/<encoded>` — caddy `handle_path /_plantuml/*` rewrites and proxies to the PlantUML server on [apps (105)](105-apps.md) `:8079`.
+- `home.tmpl` is the anonymous landing page (Homesauce hero + sign-in/explore buttons).
+- O3DV binary assets are *not* tracked — `deploy.sh` fetches them on first run.
+
+## Auto-deploy
+Push to `dtoro/gitea-customizations` master → gitea webhook → `http://127.0.0.1:9797/deploy` (loopback) → `gitea-deploy-webhook.service` validates HMAC against `/etc/gitea-deploy/secret` → runs `/opt/gitea-customizations/deploy.sh`. Then `systemctl restart gitea` if templates changed.
+
+`app.ini` `[webhook] ALLOWED_HOST_LIST` includes `127.0.0.1`, `192.168.8.175`, `192.168.8.205`, `192.168.8.230`, `192.168.8.136`, `192.168.8.77` — every webhook target across the lab. **Don't strip these when editing app.ini.** See [auto-deploy](../infrastructure/auto-deploy.md) for the full list.
+
+Git creds for the deploy service: `/etc/gitea-deploy/git-credentials` (mode 600), referenced via `credential.helper = store --file=/etc/gitea-deploy/git-credentials` in the repo's `.git/config` (because `ProtectHome=true` blocks `/root`).
+
+## DNS workaround
+LXC has `/etc/hosts` override mapping `auth.hubris.network → 192.168.8.175` (router DNS resolves the public IONOS A record, which is a dead end for LAN clients — see [DNS](../infrastructure/dns.md)). Belt-and-suspenders systemd unit `hubris-hosts-override.service` re-applies it idempotently. Override line is **outside** the `# --- BEGIN PVE ---` markers (Proxmox rewrites inside).
+
+## Related
+- [Caddy](121-caddy.md)
+- [DNS](../infrastructure/dns.md)
+- [Auto-deploy pipelines](../infrastructure/auto-deploy.md)
+- [PlantUML server lives on apps (105)](105-apps.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation.
+
+### 2026-04-22 — `app.ini` ALLOWED_HOST_LIST extended for Artifacto webhook
+Added `192.168.8.205`. See [Artifacto auto-deploy on apps (105)](105-apps.md).
+
+### 2026-04-21 — `/etc/hosts` override for `auth.hubris.network` added
+For OIDC integration with [authentik (124)](124-authentik.md). Outside the PVE markers, with a hubris-hosts-override.service for idempotency.
+
+### 2026-04-20 — gitea customizations + auto-deploy pipeline shipped
+`dtoro/gitea-customizations` repo created; webhook receiver at loopback `:9797` validates HMAC and runs `deploy.sh`. CAD and PlantUML loaders live in `footer.tmpl`.
--- a/containers/105-apps.md
+++ b/containers/105-apps.md
@@ -0,0 +1,88 @@
+# 105 — `apps`
+
+Docker host for everything that doesn't justify its own LXC. Currently runs Artifacto, Booklore, PlantUML server, Portainer (and historically WriteFreely / blog).
+
+## At a glance
+- **Hostname:** `apps`
+- **IP:** `192.168.8.205`
+- **Privilege:** privileged (so container UID = host UID for bind-mount sanity)
+- **Resources:** 2 cores / 4 GiB RAM / 30 GiB rootfs
+- **Mounts:** `/mnt/library` ↔ `/mnt/library`
+- **Public hostnames:** see table below
+
+## Public hostname → service map
+
+| Hostname                          | Container        | Backend port | Notes |
+| --------------------------------- | ---------------- | ------------ | ----- |
+| `docker.hubris.network`           | Portainer        | `:9443`      | Native OAuth2 via Authentik. Trusted-origins requires hostname only (no scheme/port). |
+| `books.hubris.network`            | Booklore         | `:6060`      | Native OIDC. Redirect URI `/oauth2-callback`. |
+| `artifacto.hubris.network`        | Artifacto        | `:3100`      | Public `/p/*`, `/static/*`, `/healthz` exposed via [VPS traefik](../infrastructure/ingress.md). |
+| `blog.hubris.network`             | WriteFreely      | `:8080`      | Native OIDC via `[oauth.generic]`. |
+| `git.hubris.network/_plantuml/*`  | PlantUML server  | `:8079`      | Same-origin route from [gitea (104)](104-gitea.md). |
+
+## Stacks
+
+### Artifacto (`/opt/artifacto/`)
+Self-hosted HTML-artifact share (Go + SQLite). Repo `dtoro/Artifacto` is the working tree itself — `git push origin main` triggers rebuild.
+- Compose: tracked `docker-compose.yml` binds `./data:/data` and `127.0.0.1:3100:3000`. `docker-compose.override.yml` uses the `!override` YAML tag on `volumes:` and `ports:` to redirect `data` to `/mnt/library/documents/artifacts`.
+- Data dir: `/mnt/library/documents/artifacts` — owner **UID 10001 : GID 10001** (matches the `app` user baked into the Dockerfile), mode 750. Parent `/mnt/library/documents` stays `www-data:www-data 750`; bind targets the child directly so no traversal needed.
+- `.env` (untracked) holds `ADMIN_PASSWORD`, `SESSION_SECRET` (`openssl rand -hex 32`), `BASE_URL=https://artifacto.hubris.network`, `SSO_GATEWAY_SECRET` (must match `ARTIFACTO_GATEWAY_SECRET` in `/etc/caddy/caddy.env` on [caddy](121-caddy.md)). Don't `git checkout .env`.
+- Auth: Authentik forward-auth on the admin surface (`/`, `/login`, `/a/*`, `/api/*`). `X-Authentik-Username` is honored only when the `X-Artifacto-Gateway` header matches `SSO_GATEWAY_SECRET` — prevents direct LAN connections from spoofing identity.
+- Public exposure: VPS traefik gates path scope to share URLs; admin surface returns 404 at the edge. See [ingress](../infrastructure/ingress.md).
+
+#### Auto-deploy pipeline (Artifacto)
+Receiver at `/opt/artifacto-deploy/` (outside the app repo): `deploy.sh` + `webhook.py`, secret in `/etc/artifacto-deploy/secret`, systemd unit `artifacto-deploy-webhook.service`. Listens on `0.0.0.0:9798`, validates `X-Gitea-Signature` HMAC-SHA256, filters to `refs/heads/main`, runs deploy in a daemon thread (returns 202 immediately). Gitea webhook id 7 on `dtoro/Artifacto`.
+
+- Logs: `pct exec 105 -- journalctl -u artifacto-deploy-webhook -f`
+- Manual deploy: `pct exec 105 -- /opt/artifacto-deploy/deploy.sh`
+- Health: `pct exec 105 -- curl -s http://127.0.0.1:9798/health` → `ok`
+- Slug length bumped 5 → 8 chars (in `internal/store/artifacts.go:41`) once the endpoint went public.
+
+### PlantUML (`/opt/plantuml/`)
+`plantuml/plantuml-server:jetty` listening on `192.168.8.205:8079`, context path `/plantuml` (`BASE_URL=plantuml`). Reached only via [gitea](104-gitea.md)'s caddy `handle_path /_plantuml/*` rewrite — no DNS record of its own. Same-origin from gitea so the embedded markdown previewer can call it without CORS.
+
+### Portainer
+Native OAuth2 (Settings → Authentication → OAuth → Custom). Manual endpoints (no OIDC discovery). Uses `portainer-uid` custom-claim scope from Authentik. Container is **not** compose-managed — safe to `docker run` recreate; data lives in named volume `portainer_data`. CLI flag: `--trusted-origins docker.hubris.network` (hostname only — `IsTrustedOrigin` rejects strings containing `://`).
+
+### Booklore
+Native OIDC via Authentik (Settings → OIDC). Redirect URI `/oauth2-callback` (NOT `/api/oidc`). Container needs `extra_hosts: auth.hubris.network:192.168.8.175`. **Edit via Portainer UI** if it's a Portainer-managed stack.
+
+> ⚠️ **Never `docker compose up` Portainer-managed stacks from the host shell.** Portainer's compose state lives at `/var/lib/docker/volumes/portainer_data/_data/compose/<N>/`. Running `docker compose up -d <svc>` from the host triggers recreates of OTHER services in the stack and silently destroys bind-mounted data. **This wiped Booklore's mariadb data on 2026-04-22.** Use the Portainer UI editor for compose changes. See [mesh migration](../infrastructure/mesh.md#critical-never-docker-compose-up-portainer-managed-stacks) for the full warning.
+
+### WriteFreely (`/opt/writefreely-docker/`)
+Native OIDC via `[oauth.generic]` in `config/config.ini`. `host = https://auth.hubris.network`, scope `openid profile email`, `map_user_id = sub`. Redirect URI in Authentik: `https://blog.hubris.network/oauth/callback/generic`. Container has `extra_hosts: auth.hubris.network:192.168.8.175`. First-time users with a local WF account must connect SSO via Customize/Settings → Linked Accounts.
+
+## Permissions
+- LXC is privileged → in-container UID == host UID.
+- Member of [media GID 10000](../infrastructure/media-permissions.md). Adding `media` to the LXC alone is *not* enough for inner Docker containers — each container needs `--group-add 10000` or `user: "<uid>:10000"` to write into `/mnt/library`.
+
+## Related
+- [Gitea (104)](104-gitea.md) — uses the PlantUML server
+- [Caddy (121)](121-caddy.md)
+- [Authentik (124)](124-authentik.md)
+- [DNS](../infrastructure/dns.md)
+- [Auto-deploy](../infrastructure/auto-deploy.md)
+- [Public ingress (Artifacto + blog)](../infrastructure/ingress.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation.
+
+### 2026-04-22 — Artifacto deployed + Authentik gateway-secret auto-login wired
+Repo `dtoro/Artifacto`. Compose, data dir, `.env`, webhook (id 7), Caddyfile site block, gateway-secret pattern, public-internet share exposure on the VPS — all set up that day. Slug length bumped 5 → 8 for brute-force resistance.
+
+### 2026-04-22 — Booklore mariadb data wiped (lesson, not a feature)
+`docker compose up -d` from the host shell on a Portainer-managed stack recreated services and re-initialized the bind-mounted `./mariadb/config`. Recovered by reseeding from snapshot. Rule recorded: edit Portainer-managed stacks via the Portainer UI.
+
+### 2026-04-22 — Portainer wired into Authentik (native OAuth2)
+Custom-claim `portainer_uid` scope. CLI added `--trusted-origins docker.hubris.network`.
+
+### 2026-04-22 — `app.ini` host whitelist on gitea extended
+Added `192.168.8.205` so the Artifacto webhook delivery wouldn't be rejected. See [gitea (104)](104-gitea.md).
+
+### 2026-04-21 — Booklore + WriteFreely wired into Authentik OIDC
+Native OIDC for both. `extra_hosts` override added inside each container so DNS resolves `auth.hubris.network` to the Caddy IP.
+
+### 2026-04-20 — PlantUML server deployed
+Used by [gitea (104)](104-gitea.md)'s footer.tmpl injection. Same-origin via caddy `handle_path /_plantuml/*` rewrite — no separate hostname.
--- a/containers/109-syncthing.md
+++ b/containers/109-syncthing.md
@@ -0,0 +1,26 @@
+# 109 — `syncthing`
+
+Cross-device file sync into `/mnt/library/syncthing`.
+
+## At a glance
+- **Hostname:** `syncthing`
+- **IP:** (none — currently stopped)
+- **Privilege:** **unprivileged** + idmap (for the `media` GID 10000 standard)
+- **Resources:** 2 cores / 2 GiB RAM / 8 GiB rootfs
+- **Mounts:** `/mnt/library` ↔ `/mnt/library`
+- **Status:** **stopped** (was running prior to 2026-04-21).
+
+## Permissions quirk
+The syncthing systemd unit runs with `User=root`, and systemd skips `initgroups()` for `User=root`. Drop-in adds `SupplementaryGroups=media` to `syncthing@.service` so it actually picks up GID 10000. See [media permissions](../infrastructure/media-permissions.md).
+
+## Related
+- [Media permissions](../infrastructure/media-permissions.md)
+- [Hubris host](../hosts/hubris.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation. Container is currently stopped — reason not yet documented; investigate before re-enabling or destroying.
+
+### 2026-04-20 — joined the `media` GID 10000 standard
+Idmap block + drop-in `SupplementaryGroups=media` on `syncthing@.service`. Config backup: `/root/109.conf.bak.*`.
--- a/containers/114-nextcloud.md
+++ b/containers/114-nextcloud.md
@@ -0,0 +1,48 @@
+# 114 — `nextcloud`
+
+Personal cloud / file collaboration. Source-of-truth for the photo libraries surfaced by [mulita (120)](120-mule-images.md).
+
+## At a glance
+- **Hostname:** `nextcloud`
+- **IP:** `192.168.8.224`
+- **Privilege:** privileged
+- **Resources:** 4 cores / 6 GiB RAM / 25 GiB rootfs
+- **Mounts:** `/mnt/library` ↔ `/mnt/library` (Nextcloud user files under `/mnt/library/homecloud`)
+- **Public hostname:** [`cloud.hubris.network`](../infrastructure/dns.md) → [caddy](121-caddy.md)
+
+## Auth
+Native OIDC via `user_oidc` app. **Username override pattern**: Authentik user `dtoro` maps to local Nextcloud user `admin` via the `nc_uid` custom-claim scope. Configured via `occ user_oidc:provider <name> --mapping-uid=nc_uid` and `--scope="openid profile email <app>-uid"`. See [Authentik](124-authentik.md#per-app-username-override-pattern-authentik) for the full pattern.
+
+Redirect URI: `/index.php/apps/user_oidc/code` (NOT `/apps/...` — pretty URLs aren't on).
+
+## DNS workaround (load-bearing)
+Nextcloud's PHP HTTP client (`OC\Http\Client\DnsPinMiddleware`) calls `dns_get_record()` directly — it bypasses `/etc/hosts`. So the Authentik OIDC discovery URL needs **real DNS** answering with `192.168.8.175` for `auth.hubris.network`. Recipe applied:
+- Local `dnsmasq` listening on `127.0.0.1:53`, `/etc/dnsmasq.d/hubris-internal.conf` with `address=/auth.hubris.network/192.168.8.175`, `server=192.168.8.1`, `server=1.1.1.1`, `interface=lo`, `bind-interfaces`, `no-hosts`, `no-resolv`.
+- `pct set 114 --nameserver "127.0.0.1 192.168.8.1 1.1.1.1"` so the LXC starts with the right resolver order.
+- `/etc/hosts` override kept as belt-and-suspenders.
+
+Also needs `allow_local_remote_servers=true` in `config.php`.
+
+> Once internal DNS at the router level handles `*.hubris.network`, this LXC-local dnsmasq can go away. See [DNS](../infrastructure/dns.md).
+
+## Storage
+Files at `/mnt/library/homecloud`. Owned by Nextcloud's own permission model — **deliberately not on the `media` group**, NC manages it itself and would complain. See [media permissions](../infrastructure/media-permissions.md).
+
+## Related
+- [mulita (120)](120-mule-images.md) — reads NC user trees + writes back via WebDAV
+- [Authentik (124)](124-authentik.md)
+- [Caddy (121)](121-caddy.md)
+- [DNS](../infrastructure/dns.md)
+- [Mesh migration (DNS overrides explained)](../infrastructure/mesh.md)
+- [Media permissions](../infrastructure/media-permissions.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation.
+
+### 2026-04-26 — Nextcloud-rooted libraries shipped (mulita)
+[mulita (120)](120-mule-images.md) now reads photos from `/nextcloud-users/<nc_user>/files/...` and writes mutations back via WebDAV. Pre-migration DB dump kept at `/root/snapshots/mulita-pre-nc-migration-20260426-075132.dump`.
+
+### 2026-04-21 — wired into Authentik (native OIDC + nc_uid override)
+Local `dnsmasq` added on this LXC because Guzzle bypasses `/etc/hosts`. Resolver order set to `127.0.0.1 192.168.8.1 1.1.1.1`. Username override `dtoro → admin`.
--- a/containers/116-heaper.md
+++ b/containers/116-heaper.md
@@ -0,0 +1,23 @@
+# 116 — `heaper`
+
+Single-purpose container for the "heaper" workload. Mounts `/mnt/library` and reads/writes under `/mnt/library/heaper`.
+
+## At a glance
+- **Hostname:** `heaper`
+- **IP:** `192.168.8.116`
+- **Privilege:** privileged
+- **Resources:** 2 cores / 2 GiB RAM / 10 GiB rootfs
+- **Mounts:** `/mnt/library` ↔ `/mnt/library`
+- **Public hostname:** none
+
+## Permissions
+Member of the [media GID 10000](../infrastructure/media-permissions.md) standard via `www-data` (the data subtree at `/mnt/library/heaper` is single-container, so it stays out of the shared setgid group treatment, but the LXC has the standard group hookup).
+
+## Related
+- [Hubris host](../hosts/hubris.md)
+- [Media permissions](../infrastructure/media-permissions.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Stub. Detail what heaper actually does the next time we touch this LXC.
--- a/containers/118-elementsynapse.md
+++ b/containers/118-elementsynapse.md
@@ -0,0 +1,32 @@
+# 118 — `elementsynapse`
+
+Matrix homeserver (Synapse). Backs `@dtoro:avispero` and `@claudio:avispero`.
+
+## At a glance
+- **Hostname:** `elementsynapse`
+- **IP:** `192.168.8.239`
+- **Privilege:** **unprivileged**
+- **Resources:** 1 core / 2 GiB RAM / 8 GiB rootfs
+- **Mounts:** none from `/mnt/library`
+- **Public hostname:** [`matrix.hubris.network`](../infrastructure/dns.md) → [caddy](121-caddy.md) → `:8008`
+- **`server_name`:** `avispero` (intentionally different from the public URL).
+
+## Service / port map
+
+| Service        | Listen  | Notes                            |
+| -------------- | ------- | -------------------------------- |
+| synapse        | `:8008` | Matrix client-server / federation HTTP. Caddy terminates TLS for `matrix.hubris.network`. |
+
+## Known issues
+- Disk usage was 86.8% at last claudio-monitor reading on 2026-04-21 — the Matrix DB grows steadily. Watch or grow rootfs.
+
+## Related
+- [claudio-bot (123)](123-claudio-bot.md) — connects directly to `192.168.8.239:8008` (avoids hairpin-NAT TLS issue on the public URL)
+- [Caddy](121-caddy.md)
+- [DNS](../infrastructure/dns.md)
+- [Monitoring](../infrastructure/monitoring.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation.
--- a/containers/119-sophia.md
+++ b/containers/119-sophia.md
@@ -0,0 +1,23 @@
+# 119 — `sophia`
+
+Single-container workload "sophia". Reads/writes under `/mnt/library/sophia`.
+
+## At a glance
+- **Hostname:** `sophia`
+- **IP:** `192.168.8.157`
+- **Privilege:** privileged
+- **Resources:** 2 cores / 1 GiB RAM / 10 GiB rootfs
+- **Mounts:** `/mnt/library` ↔ `/mnt/library`
+- **Public hostname:** none
+
+## Permissions
+LXC has `www-data` in the [media GID 10000 group](../infrastructure/media-permissions.md). The `/mnt/library/sophia` subtree itself is single-container and not on the setgid shared group.
+
+## Related
+- [Hubris host](../hosts/hubris.md)
+- [Media permissions](../infrastructure/media-permissions.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Stub. Document what runs inside next time we work on this LXC.
--- a/containers/120-mule-images.md
+++ b/containers/120-mule-images.md
@@ -0,0 +1,93 @@
+# 120 — `mule-images`
+
+Hosts `mule-image` / "mulita" — the photos app at `photos.hubris.network`. Auto-deploys from `dtoro/mule-image` on `git push origin main`.
+
+## At a glance
+- **Hostname:** `mule-images`
+- **IP:** `192.168.8.136`
+- **Privilege:** privileged
+- **Resources:** 4 cores / 8 GiB RAM / 60 GiB rootfs
+- **Mounts:** `/mnt/library` ↔ `/mnt/library`
+- **Public hostname:** [`photos.hubris.network`](../infrastructure/dns.md) → [caddy](121-caddy.md) → `:3000` (frontend)
+
+## Stack (`/opt/mule-image`)
+
+`/opt/mule-image` IS the working tree of `dtoro/mule-image`. Compose at `/opt/mule-image/docker-compose.yml`. Services:
+
+| Service           | Port   | Notes |
+| ----------------- | ------ | ----- |
+| frontend          | 3000   | Reverse-proxied by Caddy |
+| backend           | 8001   | FastAPI |
+| worker-vision     | —      | ML scan worker |
+| worker-light      | —      | Lightweight worker |
+| worker-watcher    | —      | FS watcher |
+| db                | (pg)   | pgvector |
+| redis             | (rd)   | queue |
+
+`.env` is **untracked** — `git checkout .env` will wipe it. Holds:
+- `PHOTO_DIRS=/mnt/library/images/`
+- `NEXTCLOUD_USERS_HOST_PATH=/mnt/library/homecloud`
+- `NEXTCLOUD_BASE_URL=https://cloud.hubris.network`
+- OIDC client secret + scopes
+- `SECRET_KEY` (generated)
+
+## Nextcloud-rooted libraries (since 2026-04-26)
+
+Photo libraries live under each user's Nextcloud `files/` tree, NOT in `/mnt/library/images/*`.
+- `/mnt/library/homecloud` is bind-mounted into `backend`, `worker-light`, `worker-watcher`, `worker-vision` as `/nextcloud-users`. Each NC user is `/nextcloud-users/<nc_user>/files/`.
+- Reads use that bind directly.
+- Mutations (upload, delete, rename, move) dispatch through `services/nextcloud_dav.py` (HTTP Basic auth, per-user app password Fernet-encrypted in `users.nextcloud_app_password_enc`) so Nextcloud's `oc_filecache`, trashbin, comments, and desktop-sync clients stay coherent.
+- Photo copy + cross-system moves return 501 with a "use Nextcloud's web UI" hint — defer until needed.
+- `users.nextcloud_username` overrides the default OIDC `preferred_username`. **`dtoro` (mule-image) maps to `admin` (Nextcloud)** — don't assume username equality.
+- Surviving SourceRoots in DB: `Photos` → `/nextcloud-users/admin/files/Photos`; `Memories` → `/nextcloud-users/admin/files/Memories` (both owned by `dtoro`). User `muli` has `nextcloud_username=muli` backfilled but no SourceRoot yet.
+- Pre-migration DB dump: `/root/snapshots/mulita-pre-nc-migration-20260426-075132.dump` (11 MB) on the host.
+
+## Authentication (since 2026-04-22)
+
+Native OIDC via Authentik. Code in `backend/app/auth_oidc.py`, routes `/api/v1/auth/oidc/{login,callback}`. Authentik side:
+- OAuth2/OIDC Provider, client ID `fCuHew48ONTskDjUKnMTZjFbVXuHwvQqTScQRNQ1`
+- App slug `mule-image`
+- Redirect URI: `https://photos.hubris.network/api/v1/auth/oidc/callback`
+
+Backend container needs `extra_hosts: auth.hubris.network:192.168.8.175` via `docker-compose.override.yml` (gitignored). Otherwise Authlib's metadata fetch fails with `SSL: CERTIFICATE_VERIFY_FAILED: self-signed certificate` (it ends up at a random public host because LXC DNS resolves the public IONOS A record).
+
+Caddyfile stays plain `reverse_proxy 192.168.8.136:3000` — no forward-auth, no `/api/*` bypass needed.
+
+## Auto-deploy
+
+Push to `dtoro/mule-image` `main` → gitea webhook → `http://192.168.8.136:9797/deploy` → `mule-deploy-webhook.service`:
+- Validates HMAC against `/etc/mule-deploy/secret`
+- Filters to `refs/heads/main`
+- Runs `/opt/mule-deploy/deploy.sh` in a daemon thread (returns 202 immediately — docker builds exceed gitea's request timeout)
+- `git pull --ff-only` + `docker compose up -d --build` + `docker image prune -f`
+
+Deploy tooling is **outside** the app repo: `/opt/mule-deploy/{deploy.sh,webhook.py}`, secret at `/etc/mule-deploy/secret`, unit at `/etc/systemd/system/mule-deploy-webhook.service`. Same shape as the Caddy + Artifacto pipelines. Gitea webhook id 6.
+
+`app.ini` `ALLOWED_HOST_LIST` on [gitea](104-gitea.md) includes `192.168.8.136`.
+
+Logs: `pct exec 120 -- journalctl -u mule-deploy-webhook -f`.
+Manual deploy: `pct exec 120 -- /opt/mule-deploy/deploy.sh`.
+
+For pushes from inside the LXC, gitea creds at `/etc/mule-deploy/git-credentials` (mode 600) — same token as `/etc/caddy-deploy/git-credentials` on [caddy](121-caddy.md).
+
+## Related
+- [Nextcloud (114)](114-nextcloud.md) — source of truth for photo libraries
+- [Authentik (124)](124-authentik.md)
+- [Caddy (121)](121-caddy.md)
+- [DNS](../infrastructure/dns.md)
+- [Auto-deploy](../infrastructure/auto-deploy.md)
+- [Gitea (104)](104-gitea.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation.
+
+### 2026-04-26 — Nextcloud-rooted libraries shipped
+Bind `/mnt/library/homecloud` into the workers, reads via filesystem, writes via WebDAV. `users.nextcloud_username` override field added; `dtoro → admin` mapping. Surviving SourceRoots cleaned up to NC paths.
+
+### 2026-04-22 — native OIDC via Authentik
+Authlib-based code in `backend/app/auth_oidc.py`. `extra_hosts` override for `auth.hubris.network` in compose override (gitignored).
+
+### 2026-04-21 — auto-deploy pipeline shipped
+Webhook receiver at `:9797`, async deploy returning 202. Mirrors caddy-conf / gitea-customizations.
--- a/containers/121-caddy.md
+++ b/containers/121-caddy.md
@@ -0,0 +1,81 @@
+# 121 — `caddy`
+
+The reverse proxy. Terminates TLS for every `*.hubris.network` hostname on the LAN/mesh and forwards to the right backend.
+
+## At a glance
+- **Hostname:** `caddy`
+- **IP:** `192.168.8.175`
+- **Privilege:** **unprivileged**
+- **Resources:** 1 core / 512 MiB RAM / 6 GiB rootfs
+- **Mounts:** none from `/mnt/library`
+- **Config:** `/etc/caddy/Caddyfile` is a [git checkout of `dtoro/caddy-conf`](#auto-deploy)
+- **Cert source:** Let's Encrypt **DNS-01** via IONOS API (`IONOS_AUTH_API_TOKEN`).
+
+## Sites currently served (live as of 2026-04-28)
+
+- `artifacto.hubris.network` → [apps (105)](105-apps.md) `:3100`
+- `auth.hubris.network` → [authentik (124)](124-authentik.md) `:9000`
+- `blog.hubris.network` → [apps (105)](105-apps.md) `:8080`
+- `books.hubris.network` → [apps (105)](105-apps.md) `:6060`
+- `cloud.hubris.network` → [nextcloud (114)](114-nextcloud.md) `:443`
+- `docker.hubris.network` → [apps (105)](105-apps.md) `:9443`
+- `git.hubris.network` → [gitea (104)](104-gitea.md) `:3000` (+ `handle_path /_plantuml/*` → apps `:8079`)
+- `home.hubris.network` → [haos VM (108)](../vms/108-haos.md) `192.168.8.101:8123`
+- `jellyseerr.hubris.network` → [arriman (122)](122-arriman.md) `:5056`
+- `matrix.hubris.network` → [elementsynapse (118)](118-elementsynapse.md) `:8008`
+- `media.hubris.network` → [jellyfin (101)](101-jellyfin.md) `:8096`
+- `paperless.hubris.network` → [paperless (103)](103-paperless.md) `:8000`
+- `photos.hubris.network` → [mule-images (120)](120-mule-images.md) `:3000`
+- `proxmox.hubris.network` → [hubris host](../hosts/hubris.md) `:8006`
+- `qbit.hubris.network` → [arriman (122)](122-arriman.md) `:8080`
+- `sab.hubris.network` → [arriman (122)](122-arriman.md) `:8081`
+
+> **Reminder:** Caddy alone isn't enough to make a new subdomain reachable on the LAN. Each one needs an entry in [DNS split-horizon](../infrastructure/dns.md) too.
+
+## Snippet: `(authentik)` forward-auth
+
+A snippet at the top of the Caddyfile (used as `import authentik` in any site block) wires forward-auth to the embedded Authentik outpost. It points at `http://192.168.8.180:9000` directly (NOT `https://auth.hubris.network`) to avoid Caddy-to-self round-tripping that strips `X-Forwarded-Host`. The forward-auth block must explicitly set `header_up X-Forwarded-Host {host}`. See [Authentik](124-authentik.md#forward-auth-domain-level-setup).
+
+For apps with mobile clients, `/api/*` (or equivalent) bypasses forward-auth — see the per-app gotchas in [Authentik](124-authentik.md).
+
+## Caddy environment
+
+Untracked secrets in `/etc/caddy/caddy.env`:
+- `IONOS_AUTH_API_TOKEN` — DNS-01 ACME
+- `ARTIFACTO_GATEWAY_SECRET` — must match `SSO_GATEWAY_SECRET` on [apps (105)](105-apps.md). Rotate together.
+
+## Auto-deploy
+
+Push to `dtoro/caddy-conf` master → gitea webhook → `http://192.168.8.175:9797/deploy` → `caddy-deploy-webhook.service` validates HMAC against `/etc/caddy-deploy/secret` → runs `/etc/caddy/scripts/deploy.sh`:
+1. `git pull`
+2. `caddy validate`
+3. `systemctl reload caddy`
+
+Gitea webhook id 2 on `dtoro/caddy-conf`. Receiver, deploy script, install scripts, systemd unit all live in the repo under `scripts/`. The unit has `ReadWritePaths=/etc/caddy` — load-bearing (`ProtectSystem=full` would otherwise block `git pull`). Git credentials for the root-run service are at `/etc/caddy-deploy/git-credentials` (mode 600).
+
+> **Systemd unit changes inside the repo do NOT auto-reinstall** — you have to re-run `scripts/webhook/install.sh` manually after editing the unit.
+
+## Related
+- [DNS split-horizon](../infrastructure/dns.md) — must add entry for every new subdomain
+- [Authentik (124)](124-authentik.md) — forward-auth + IdP
+- [Auto-deploy](../infrastructure/auto-deploy.md)
+- [Public ingress (VPS traefik)](../infrastructure/ingress.md) — mirrors Caddy's certs to the VPS for public exposure
+- [Gitea (104)](104-gitea.md) — webhook source
+- All container pages list their Caddy backend.
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation. 16 active sites at this date.
+
+### 2026-04-22 — Artifacto + Authentik gateway-secret pattern wired
+Caddy site `artifacto.hubris.network`: forward-auth on admin paths, `header_up X-Artifacto-Gateway {env.ARTIFACTO_GATEWAY_SECRET}`, public matchers `/p/*`, `/static/*`, `/healthz`. `caddy.env` extended with the gateway secret.
+
+### 2026-04-21 — `(authentik)` snippet added
+Top-of-file snippet used by every gated site. Targets `http://192.168.8.180:9000` directly to dodge hairpin TLS round-trip.
+
+### 2026-04-21 — three new sites added (jellyseerr, qbit, sab → 192.168.8.132)
+For the [arriman (122)](122-arriman.md) docker stack. Caddy + certs work; needed corresponding [DNS split-horizon](../infrastructure/dns.md) entries to be added to land cleanly.
+
+### 2026-04-20 — auto-deploy pipeline shipped
+Repo `dtoro/caddy-conf`. Webhook receiver at `:9797`, validate + reload on push to master.
--- a/containers/122-arriman.md
+++ b/containers/122-arriman.md
@@ -0,0 +1,111 @@
+# 122 — `arriman`
+
+Docker host running the \*arr stack via [`ezarr`](https://github.com/ezarr/ezarr) compose. Replaced the old yunohost-based [LXC 100](index.md#recently-destroyed-kept-for-archaeology) on 2026-04-21.
+
+## At a glance
+- **Hostname:** `arriman`
+- **IP:** `192.168.8.132`
+- **Privilege:** privileged
+- **Resources:** 4 cores / 8 GiB RAM / 24 GiB rootfs
+- **Mounts:** `/mnt/library` ↔ `/mnt/library`
+- **Public hostnames:** `jellyseerr` / `qbit` / `sab` (see below)
+
+## Compose
+
+`/home/arr/ezarr/docker-compose.yml`. Network `ezarr_default` `172.18.0.0/16`. Service users all run with primary GID 10000 (host `media` group) inside their containers — see [media permissions](../infrastructure/media-permissions.md). Per-app `/config/<app>-config/` dirs bind to `/config` inside.
+
+`.env` contents:
+- `DOWNLOADS_DIR=/mnt/library/downloads/`
+- `MEDIA_DIR=/mnt/library/`
+- `MEDIACENTER_GID=10000` ← **must be 10000, not 13000.** s6-setuidgid only honors the primary PGID; `group_add:` doesn't propagate. Without this, qBit errors every torrent with "Permission denied".
+- `SONARR_UID=13001`, `RADARR_UID=13002`, `LIDARR_UID=13003`, `PROWLARR_UID=13006`, `JELLYSEERR_UID=13012`, `BAZARR_UID=13013`, `QBITTORRENT_UID`, `SABNZBD_UID`
+
+## Service / port map
+
+| Service       | Host:Container | Public hostname                      |
+| ------------- | -------------- | ------------------------------------ |
+| sonarr        | `8989:8989`    | direct only                          |
+| radarr        | `7878:7878`    | direct only                          |
+| lidarr        | `8686:8686`    | direct only                          |
+| prowlarr      | `9696:9696`    | direct only                          |
+| bazarr        | `6767:6767`    | direct only                          |
+| jellyseerr    | `5056:5055`    | [`jellyseerr.hubris.network`](../infrastructure/dns.md) |
+| qbittorrent   | `8080:8080`    | [`qbit.hubris.network`](../infrastructure/dns.md)       |
+| sabnzbd       | `8081:8080`    | [`sab.hubris.network`](../infrastructure/dns.md)        |
+| flaresolverr  | `8191:8191`    | internal only                        |
+
+Internal *arr ↔ *arr / *arr ↔ qBit/SAB/flaresolverr comms run on `ezarr_default` using docker service names.
+
+## Categories (qBit + SAB + *arr)
+
+| Category | qBit savePath               | SAB dir | Consumer                          |
+| -------- | --------------------------- | ------- | --------------------------------- |
+| tv       | `/data/torrents/tv`         | tv      | Sonarr                            |
+| movies   | `/data/torrents/movies`     | movies  | Radarr                            |
+| music    | `/data/torrents/music`      | music   | Lidarr                            |
+| anime    | `/data/torrents/anime`      | anime   | Sonarr (2nd download client, root `/data/media/anime`) |
+| books / audiobooks / comics / podcasts | `/data/torrents/<cat>` | `<cat>` | (reserved, none in use yet) |
+
+Path mapping: host `/mnt/library/<cat>` ↔ container `/data/media/<cat>`. Downloads: host `/mnt/library/downloads/<torrents|usenet>/<cat>` ↔ container `/data/torrents/<cat>` and `/data/usenet/<cat>`.
+
+## Auth (qBit reverse-proxy + Authentik forward-auth)
+
+qBit auto-login behind forward-auth via IP whitelist. `qBittorrent.conf` lines:
+- `WebUI\AuthSubnetWhitelist=172.18.0.0/16, 172.17.0.0/16, 192.168.8.175/32`
+- `WebUI\ReverseProxySupportEnabled=true`
+- `WebUI\TrustedReverseProxiesList=192.168.8.175, 172.18.0.0/16`
+
+> **Stop the container before editing `qBittorrent.conf`.** qBit writes its in-memory config on graceful shutdown and clobbers any live edits. Recipe: `docker stop qbittorrent && sed -i ... && docker start qbittorrent`.
+
+Mobile/desktop clients keep working via `/api/v2/*` path bypass on Caddy.
+
+SABnzbd `host_whitelist`: `sabnzbd, localhost, 127.0.0.1, 192.168.8.132, sab.hubris.network` — extend before accessing SAB from a new host.
+
+## Credentials
+
+Backups of all migration-time secrets at `/mnt/library/backup/arr-migration-2026-04-21/state/`:
+- `lxc100-apikey-{sonarr,radarr,prowlarr,lidarr}.txt`
+- `qbit-creds.txt`, `sab-creds.txt`
+- `lxc100-jellyseerr-settings.json`
+
+\*arr API keys were preserved from the yunohost DB — don't rotate unless needed.
+
+qBittorrent: `admin` / `CDyjxMKvjfGupCKzXFkjsKw4nRrXMRL`.
+
+## Migration gotchas (apply if ever re-importing)
+
+- Imported \*arr `config.xml`: must have `<BindAddress>*</BindAddress>`, `<Port>{ezarr-port}</Port>`, `<UrlBase></UrlBase>`. Otherwise app listens only on 127.0.0.1, wrong port, wrong path.
+- Imported DB paths must be rewritten `/mnt/library/` → `/data/media/` (RootFolders / Series / Movies / Artists tables). Without this, scans and imports fail silently.
+- Bazarr `config/config.yaml` (yaml, not ini) — `ip: 0.0.0.0`, `port: 6767`, empty top-level `base_url`; sonarr/radarr connection sections normalized to docker service names.
+- Staging dir for migrations: `/mnt/library/backup/stage/<app>/` (visible to both old LXC 100 and arriman because both bind-mount the same host path).
+
+## Permissions
+
+Member of [media GID 10000](../infrastructure/media-permissions.md). The LXC has `www-data, audiobookshelf, radarr, sonarr, lidarr, prowlarr, qbittorrent, bazarr, jellyseerr, mylar, jackett, overseerr, plex, arr` in the `media` group. Each docker container also receives GID 10000 as its primary group via `MEDIACENTER_GID=10000`.
+
+## Rollback material (kept until 2026-04-28+)
+
+`/mnt/library/backup/arr-migration-2026-04-21/`:
+- `tars/` — per-subtree tars of yunohost app data (granular restore)
+- `snapshots/` — vzdumps of LXC 100 (pre-migration) and LXC 122 (pre-import), plus post-stop vzdumps of LXC 100 + 106
+- `stage/<app>-preimport.tar.gz` — original empty ezarr `/config/<app>-config/` dirs
+- `state/` — service dumps, listening ports, API keys, jellyseerr settings at migration time
+- `DESTROY_AFTER_2026-04-28.md` — destroy checklist + post-destroy restore commands
+
+## Related
+- [Caddy (121)](121-caddy.md)
+- [Authentik (124)](124-authentik.md) — forward-auth wiring + per-app `/api/*` bypass
+- [DNS](../infrastructure/dns.md)
+- [Media permissions](../infrastructure/media-permissions.md)
+- [Hubris host](../hosts/hubris.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation.
+
+### 2026-04-26 — `MEDIACENTER_GID` flipped 13000 → 10000
+qBit was erroring every torrent with "Permission denied" because s6-setuidgid only honors the primary PGID and `group_add:` doesn't propagate. Setting the primary GID to 10000 (the host `media` group) fixed it.
+
+### 2026-04-21 — \*arr stack migrated yunohost → docker-compose
+Old LXC 100 stopped; ezarr stack stood up here; data and DBs imported with path rewrites. flaresolverr folded in from old LXC 106. Three Caddy sites added (jellyseerr, qbit, sab) → see [caddy](121-caddy.md). Rollback artifacts under `/mnt/library/backup/arr-migration-2026-04-21/`.
--- a/containers/123-claudio-bot.md
+++ b/containers/123-claudio-bot.md
@@ -0,0 +1,79 @@
+# 123 — `claudio-bot`
+
+Matrix-resident control plane. Bot account `@claudio:avispero` joined to a private room; accepts slash commands and natural language; relays infra notifications.
+
+## At a glance
+- **Hostname:** `claudio-bot`
+- **IP:** `192.168.8.230`
+- **Privilege:** **unprivileged**
+- **Resources:** 1 core / 512 MiB RAM / 8 GiB rootfs
+- **Mounts:** none from `/mnt/library`
+- **Public hostname:** none
+
+## Stack
+
+Repo `dtoro/claudio-bot`, checkout at `/opt/claudio-bot`, systemd unit `claudio-bot.service`. Connects to Matrix at `http://192.168.8.239:8008` (direct LAN to [synapse (118)](118-elementsynapse.md), avoids hairpin-NAT TLS issue on `matrix.hubris.network`).
+
+Room: `!dEUVJArVKPorxHHJZK:avispero` (invite-only, `@dtoro:avispero` allowed).
+
+## Configuration
+
+Secrets at `/etc/claudio-bot/` (mode 600):
+- `config.yaml`
+- `matrix.token`
+- `anthropic.key`
+- `lmstudio.key`
+- `ipc.token`
+
+Deploy git creds at `/etc/claudio-deploy/git-credentials`.
+
+### LLM backend (pluggable)
+
+`llm.backend` in `config.yaml`:
+- `anthropic` — Claude API via `anthropic.key`
+- `lmstudio` — OpenAI-compat HTTP via `lmstudio.key` (bearer)
+
+Currently set to `lmstudio` → `google/gemma-4-e4b` on the Mac mini at `192.168.8.174:1234` (since 2026-04-25). Switch back with `backend:` + `systemctl restart claudio-bot`. Original config saved at `/etc/claudio-bot/config.yaml.bak`. The LM Studio agent in `bot_core/lmstudio.py` translates Anthropic → OpenAI tool definitions.
+
+## IPC
+
+`http://192.168.8.230:9090/{notify,propose,status}`. Header `X-Bot-Token` must match `/etc/claudio-bot/ipc.token`. Used by:
+- [claudio-monitor on hubris](../infrastructure/monitoring.md) for edge-triggered alerts (token in `/etc/claudio-monitor/bot.token`)
+- The (currently disabled) [restic backup wrapper](../infrastructure/backups.md) (token in `/etc/restic/bot.token`)
+
+> Token files at the source side **must hold the same value as `/etc/claudio-bot/ipc.token`** — rotate together.
+
+## Plugins
+
+Module under `plugins/<name>.py` exposing a `Plugin` class; add `<name>` to `plugins:` in `config.yaml`. Plugins can register slash commands, Claude tools, and `on_notify` / `on_proposal_response` hooks.
+
+Active plugins:
+- `system` — `ping`, `help`, `status`, `list_plugins`
+- `backup` — ingests `/notify` from the backup wrapper (currently silent — backups disabled)
+- `monitor` — `/monitor status`, `/monitor history [N]`, `/monitor clear <key>`. Tools: `get_alerts`, `get_monitor_history` for NL queries via Claude.
+
+## Auto-deploy
+
+Push to `dtoro/claudio-bot` → gitea webhook → `http://192.168.8.230:9797/deploy` → pull + `pip install` + restart. Same shape as caddy-conf.
+
+`app.ini` `ALLOWED_HOST_LIST` on [gitea](104-gitea.md) includes `192.168.8.230`.
+
+## Related
+- [elementsynapse (118)](118-elementsynapse.md)
+- [Monitoring (claudio-monitor)](../infrastructure/monitoring.md)
+- [Backups (disabled)](../infrastructure/backups.md)
+- [Auto-deploy](../infrastructure/auto-deploy.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation.
+
+### 2026-04-25 — LLM backend switched to LM Studio
+`backend: lmstudio` → `google/gemma-4-e4b` on the Mac mini. Anthropic key still present so the swap is reversible by flipping the config field.
+
+### 2026-04-21 — `monitor` plugin added
+Receives events from [claudio-monitor](../infrastructure/monitoring.md). Slash commands + tools registered. See `dtoro/claudio-bot` commit `e56da25`.
+
+### 2026-04-20 — claudio-bot deployed
+LXC 123 provisioned. Repo, systemd unit, Matrix wiring, `system` + `backup` plugins, IPC server.
--- a/containers/124-authentik.md
+++ b/containers/124-authentik.md
@@ -0,0 +1,136 @@
+# 124 — `authentik`
+
+Central Identity Provider for the lab. Also runs the [split-horizon dnsmasq](../infrastructure/dns.md) — ergo "the SSO and DNS box".
+
+## At a glance
+- **Hostname:** `authentik`
+- **IP:** `192.168.8.180` (statically configured — the only LXC with a static IP)
+- **Privilege:** privileged
+- **Resources:** 2 cores / 4 GiB RAM / 20 GiB rootfs
+- **Mounts:** none from `/mnt/library`
+- **Public hostname:** [`auth.hubris.network`](../infrastructure/dns.md) → [caddy (121)](121-caddy.md) → `:9000`
+- **Container DNS (in `/etc/pve/lxc/124.conf`):** `192.168.8.1 1.1.1.1` (router DNS plus a fallback added 2026-04-21 because router DNS flakes intermittently — Authentik is the resolver itself for the *rest* of the LAN, but its own LXC uses upstream).
+
+## Authentik stack (`/opt/authentik/`)
+
+Upstream `docker-compose.yml` + `.env`. Services: `postgresql` (16-alpine), `server`, `worker`. Authentik 2026.x dropped the Redis dependency.
+
+- `.env` mode 600, **untracked**, holds `AUTHENTIK_SECRET_KEY` and `PG_PASS`.
+- `AUTHENTIK_TAG=2026.2.2` — pinned. Don't let it drift to `:latest`. Telemetry / update-check / error-reporting disabled.
+- Ports: 9000 (http), 9443 (https) on the LXC.
+- Embedded outpost lives at `/outpost.goauthentik.io/*` on the Authentik host — the forward-auth endpoint Caddy points at.
+- Stack is **not** git-tracked yet. If/when wiring auto-deploy: mirror the `mule-image` pattern (webhook receiver outside the app repo at `/opt/authentik-deploy/`). Repo `dtoro/authentik-conf` is reserved but not created.
+
+## Forward-auth pattern (every gated app)
+
+- **One Proxy Provider per app.** Authentik enforces a UNIQUE constraint `application.provider_id`, so one Provider = one Application. "Domain-level" only means they share the cookie domain. Each provider in "Forward auth (domain level)" mode, External host `https://auth.hubris.network`, Cookie domain `hubris.network`. First one was `hubris-forward-auth` (Paperless).
+- **Authentication flow:** MUST be `default-authentication-flow` (NOT `default-source-authentication` — that's for IdP federation; gives `FlowNonApplicableException` + 404 on the authorize endpoint).
+- **Authorization flow:** `default-provider-authorization-implicit-consent` (or explicit).
+- **Application Launch URL** MUST be the full public URL `https://<sub>.hubris.network/` — outpost matches incoming `X-Forwarded-Host` against it.
+- Each Application MUST have at least one **policy/group/user binding** — zero bindings = outpost returns 404 on access.
+- **Restart Authentik after binding new apps to the outpost:**
+  ```
+  pct exec 124 -- docker compose -f /opt/authentik/docker-compose.yml restart server worker
+  ```
+
+Caddy snippet `(authentik)` lives at the top of `/etc/caddy/Caddyfile`. Points at `http://192.168.8.180:9000` directly (NOT `https://auth.hubris.network`) to avoid hairpin TLS round-trip stripping `X-Forwarded-Host`. Must explicitly set `header_up X-Forwarded-Host {host}` in the forward-auth block. Used by gated sites with `import authentik`.
+
+### Per-app username override pattern (Authentik)
+
+Used when the app's local user ID doesn't match the user's Authentik username (e.g., Nextcloud's `admin` ≠ Authentik's `dtoro`).
+
+1. On the Authentik user: add attribute `<app>_uid: <target_local_username>` (YAML, Directory → Users → Edit → Attributes).
+2. Customization → Property Mappings → Create → **Scope Mapping** (not SAML):
+   - Name: `<app>-uid-override`, Scope name: `<app>-uid`, Expression:
+     ```python
+     return {"nc_uid": user.attributes.get("<app>_uid", user.username)}
+     ```
+   - **Use a custom claim key** (e.g. `nc_uid`), not `preferred_username` — the default `profile` scope mapping emits `preferred_username` and will overwrite yours depending on ordering.
+3. Attach the new scope to the provider (Providers → app → Scopes).
+4. On the app side, point its OIDC UID-mapping setting at the custom claim.
+
+For Nextcloud:
+```
+occ user_oidc:provider <name> --mapping-uid=nc_uid
+occ user_oidc:provider <name> --scope="openid profile email <app>-uid"
+```
+
+### Bypass forward-auth for API paths (mobile apps)
+
+If the app has its own token-based API auth and a mobile client, API paths must bypass forward-auth — mobile apps can't follow the browser login redirect. Pattern in the Caddyfile site block:
+
+```
+paperless.hubris.network {
+    tls { dns ionos {env.IONOS_AUTH_API_TOKEN} }
+    @api path /api/*
+    handle @api {
+        reverse_proxy 192.168.8.130:8000
+    }
+    handle {
+        import authentik
+        reverse_proxy 192.168.8.130:8000
+    }
+}
+```
+
+API paths to bypass per app:
+- [Paperless](103-paperless.md): `/api/*` (Bearer)
+- [Sonarr / Radarr / Lidarr / etc.](122-arriman.md): `/api/*` (X-Api-Key)
+- [qBittorrent](122-arriman.md): `/api/*` (session cookie from `/api/v2/auth/login`)
+- [SABnzbd](122-arriman.md): `/api?*` (apikey query param) — match `/api*` for query-string APIs
+- Homarr: no mobile client
+- [Portainer](105-apps.md): mobile uses same session auth as web; no bypass typically needed
+
+### Backend trust of Authentik headers (skip the app's own login after SSO)
+
+- [**Paperless**](103-paperless.md): `PAPERLESS_ENABLE_HTTP_REMOTE_USER=true` and `PAPERLESS_HTTP_REMOTE_USER_HEADER_NAME=HTTP_X_AUTHENTIK_USERNAME` in `/opt/paperless/paperless.conf`. Restart `paperless-webserver paperless-task-queue paperless-scheduler paperless-consumer`. Django auto-creates matching users on first SSO login; promote to superuser via existing admin UI.
+- Apps without header-auth support: users log in twice (SSO + app login). Acceptable but degraded UX.
+
+## Per-app integration map
+
+| App                                       | Type             | Notes |
+| ----------------------------------------- | ---------------- | ----- |
+| [Paperless (103)](103-paperless.md)       | Forward-auth + REMOTE_USER | `/api/*` bypass |
+| [Nextcloud (114)](114-nextcloud.md)       | Native OIDC      | `nc_uid` override; local dnsmasq required (Guzzle bypasses `/etc/hosts`) |
+| [mulita (120)](120-mule-images.md)        | Native OIDC      | `extra_hosts` override in compose |
+| [Booklore (105)](105-apps.md)             | Native OIDC      | Redirect URI `/oauth2-callback`; `extra_hosts` |
+| [Portainer (105)](105-apps.md)            | Native OAuth2    | `portainer_uid` custom claim; `--trusted-origins` flag |
+| [WriteFreely (105)](105-apps.md)          | Native OIDC      | `[oauth.generic]` block; `extra_hosts` |
+| [qBittorrent (122)](122-arriman.md)       | Forward-auth via IP whitelist | Reverse-proxy support enabled in qBit |
+| [Artifacto (105)](105-apps.md)            | Forward-auth + gateway-secret auto-login | Public `/p/*` paths bypass |
+| [Home Assistant VM (108)](../vms/108-haos.md) | HACS `christiaangoossens/hass-oidc-auth` | `automatic_user_linking: true`, `default_redirect: true`. Supervisor DNS via `ha dns options`. |
+
+## Netbird IdP integration — DEFERRED
+
+The `netbirdio/netbird-server` combined image has no config knobs for external OIDC. Verified in `combined/cmd/config.go` on main (v0.69.0): `AuthConfig` only exposes issuer + redirect URIs; `ToManagementConfig()` hardcodes `AuthAudience="netbird-dashboard"`, `UserIDClaim="sub"`, always calls `buildEmbeddedIdPConfig()`. Code comment: `"embedded IdP is always enabled in combined server"`.
+
+To wire Authentik into Netbird login/user-sync, must migrate to the legacy split stack (`netbirdio/management` + `signal` + `dashboard` + coturn) with the richer `management.json` schema. Sqlite management data should migrate but needs verification; peers stay connected via wireguard keys.
+
+**Pre-work already in place (keep for re-use):**
+- Provider `Provider for Netbird` + App `netbird`. Client ID `xZwVTFCsxWdBM3uIGS15wAAcVvsJiTtWdxVCEela`. Redirect URIs for `https://netbird.hubris.network/{nb-auth,nb-silent-auth}` and `http://localhost:53000/`. Scopes: `openid profile email offline_access goauthentik.io/api`.
+- Service account `netbird-service` in `authentik Admins` group, non-expiring API token `netbird-service-api`.
+- Netbird mgmt host (`82.165.190.79`) is now a peer on its own mesh. See [mesh](../infrastructure/mesh.md).
+
+## DNS responsibility
+
+dnsmasq runs alongside Authentik on this LXC, listening on `192.168.8.180:53` + `127.0.0.1:53`, serving every `*.hubris.network` subdomain → `192.168.8.175`. **There is no wildcard** — every site needs an explicit `address=` entry. See [DNS split-horizon](../infrastructure/dns.md).
+
+## Related
+- [DNS split-horizon](../infrastructure/dns.md)
+- [Caddy (121)](121-caddy.md)
+- [Mesh migration](../infrastructure/mesh.md)
+- Every gated app under [containers/index](index.md)
+
+## Changelog
+
+### 2026-04-28 — wiki entry created
+Initial documentation.
+
+### 2026-04-22 — Phase 6 (Netbird IdP swap) deferred
+Combined netbird-server image can't take an external IdP. Pre-work in Authentik kept for later. Netbird mgmt host instead joined its own mesh as a peer (`100.122.165.149`) for split-horizon DNS access.
+
+### 2026-04-22 — Artifacto, mulita, WriteFreely, Portainer wired
+Native OIDC for mulita / WriteFreely / Portainer; gateway-secret auto-login pattern for Artifacto.
+
+### 2026-04-21 — deployed; Phases 1–5 complete
+LXC 124 provisioned, stack at `/opt/authentik`, public URL via Caddy, Paperless + Booklore + Nextcloud + Home Assistant wired. dnsmasq for split-horizon DNS lives on the same LXC.
--- a/containers/index.md
+++ b/containers/index.md
@@ -0,0 +1,47 @@
+# LXC containers — index
+
+All containers live on [`hubris`](../hosts/hubris.md). Each row links to the per-container page.
+
+| ID  | Name             | IP              | Priv | Cores | RAM   | Disk  | Mounts                | Public hostname                       | Status   |
+| --- | ---------------- | --------------- | ---- | ----- | ----- | ----- | --------------------- | ------------------------------------- | -------- |
+| 101 | [jellyfin](101-jellyfin.md)             | 192.168.8.206 | unpriv (idmap) | 2 | 4 GiB  | 16 GiB | `/mnt/library`        | `media.hubris.network`                | running  |
+| 103 | [paperless](103-paperless.md)           | 192.168.8.130 | priv | 2 | 3 GiB  | 8 GiB  | `/mnt/library`        | `paperless.hubris.network`            | running  |
+| 104 | [gitea](104-gitea.md)                   | 192.168.8.121 | priv | 1 | 1 GiB  | 8 GiB  | `/mnt/library`        | `git.hubris.network`                  | running  |
+| 105 | [apps](105-apps.md)                     | 192.168.8.205 | priv | 2 | 4 GiB  | 30 GiB | `/mnt/library`        | `docker` / `books` / `artifacto` / `blog` | running |
+| 109 | [syncthing](109-syncthing.md)           | (stopped)     | unpriv (idmap) | 2 | 2 GiB  | 8 GiB  | `/mnt/library`        | —                                     | **stopped** |
+| 114 | [nextcloud](114-nextcloud.md)           | 192.168.8.224 | priv | 4 | 6 GiB  | 25 GiB | `/mnt/library`        | `cloud.hubris.network`                | running  |
+| 116 | [heaper](116-heaper.md)                 | 192.168.8.116 | priv | 2 | 2 GiB  | 10 GiB | `/mnt/library`        | —                                     | running  |
+| 118 | [elementsynapse](118-elementsynapse.md) | 192.168.8.239 | unpriv | 1 | 2 GiB  | 8 GiB  | —                     | `matrix.hubris.network`               | running  |
+| 119 | [sophia](119-sophia.md)                 | 192.168.8.157 | priv | 2 | 1 GiB  | 10 GiB | `/mnt/library`        | —                                     | running  |
+| 120 | [mule-images](120-mule-images.md)       | 192.168.8.136 | priv | 4 | 8 GiB  | 60 GiB | `/mnt/library`        | `photos.hubris.network`               | running  |
+| 121 | [caddy](121-caddy.md)                   | 192.168.8.175 | unpriv | 1 | 512 MiB | 6 GiB  | —                     | (terminates all `*.hubris.network`)   | running  |
+| 122 | [arriman](122-arriman.md)               | 192.168.8.132 | priv | 4 | 8 GiB  | 24 GiB | `/mnt/library`        | `jellyseerr` / `qbit` / `sab`         | running  |
+| 123 | [claudio-bot](123-claudio-bot.md)       | 192.168.8.230 | unpriv | 1 | 512 MiB | 8 GiB | —                     | —                                     | running  |
+| 124 | [authentik](124-authentik.md)           | 192.168.8.180 | priv | 2 | 4 GiB  | 20 GiB | —                     | `auth.hubris.network`                 | running  |
+
+## Recently destroyed (kept for archaeology)
+
+| ID  | Name             | Destroyed       | Reason                                        |
+| --- | ---------------- | --------------- | --------------------------------------------- |
+| 100 | arr (yunohost)   | ~2026-04-28     | Migrated to docker stack on [arriman](122-arriman.md); planned retention window expired |
+| 106 | flaresolverr     | ~2026-04-28     | Folded into the arriman docker compose       |
+| 107 | marimo           | between 2026-04-21 and 2026-04-28 | Decommissioned                |
+| 110 | photoprism       | between 2026-04-21 and 2026-04-28 | Replaced by [mulita](120-mule-images.md) |
+| 111 | karakeep         | between 2026-04-21 and 2026-04-28 | Decommissioned                |
+| 112 | immich           | between 2026-04-21 and 2026-04-28 | Replaced by [mulita](120-mule-images.md) |
+| 115 | reticulum        | between 2026-04-21 and 2026-04-28 | Decommissioned                |
+
+> Several `.conf.bak` files survive under `/etc/pve/lxc/` if you need to recover any of the configs.
+
+## Conventions
+
+- All net0 are `bridge=vmbr0`, `ip=dhcp` except [124 (authentik)](124-authentik.md) which is statically `192.168.8.180/24`. IPs are stable via the LAN router's DHCP reservations.
+- `onboot=1` on every container — the host brings them up after `pve-guests.service`.
+- Bind mounts are declared as `mp0: /mnt/library,mp=/mnt/library`. Containers that don't mount `/mnt/library` don't need it.
+- Most containers are privileged. Unprivileged ones (`101`, `109`, `118`, `121`, `123`) require an idmap block in their conf to participate in the [media GID 10000](../infrastructure/media-permissions.md) standard.
+
+## Related
+- [Hubris host](../hosts/hubris.md)
+- [Media permissions](../infrastructure/media-permissions.md)
+- [Caddy](121-caddy.md) — terminates every public hostname
+- [DNS](../infrastructure/dns.md) — split-horizon entries for each subdomain