docs: FrankBook-Pro page + 2026-09-01 log

Document the Mac *arr/qBittorrent stack (VM placement, gluetun credential gate, socat LaunchAgents, PBKDF2 qB seed) and log the day: dankserver recovery + full quadlet cutover of the six media services, the frankbook skip-propagation/PBKDF2 handler fix, the 7-service frankbook deploy, and the jellyfin GPU-parity finding.
2026-09-01 14:32:57 -07:00
parent 1a257c06fe
commit b6be6d3da6
3 changed files with 75 additions and 0 deletions
@@ -0,0 +1,67 @@
+---
+type: reference
+description: FrankBook-Pro — the Mac mini running the *arr stack + qBittorrent inside a podman machine VM, gluetun-gated
+tags: [frankbook-pro, mac, arr, qbittorrent, gluetun, wireguard, podman-machine]
+timestamp: 2026-09-01
+---
+
+# FrankBook-Pro
+
+FrankBook-Pro (192.168.0.112, macOS x86_64, Intel) runs the *arr automation
+stack and qBittorrent inside a **podman machine** VM (Fedora CoreOS-style
+`core` user). Seven quadlet units live in `frankbook-pro/<svc>/quadlet/`:
+`gluetun`, `qbittorrent`, `prowlarr`, `sonarr`, `radarr`, `lidarr`, `readarr`.
+
+## Why a VM, and why inside it
+
+- macOS podman runs containers inside a VM; quadlet units are installed in the
+  VM (`/home/core/.config/containers/systemd/`) via `podman machine ssh`.
+- `/Volumes/COMPLETE` (review disk) and `/Volumes/INCOMPLETE` (in-progress
+  disk) are virtiofs-mounted into the VM, so qBittorrent writes straight to
+  the same disks the human review workflow uses.
+- Grab-only stack: the arrs never auto-import; nothing writes to the entropy
+  volume. Completed files land in `/Volumes/COMPLETE/Finished Torrents`.
+
+## WireGuard gate (gluetun)
+
+qBittorrent downloads through gluetun (netns share); the arrs run without it.
+Until `/home/core/Containers/gluetun/env` contains the WireGuard credentials
+(a second peer for the Mac — reusing Dankclaw's key would flip its tunnel and
+kill SearXNG), `deploy_frankbook_stack` **skips** gluetun and qbittorrent
+with instructions and deploys the five arrs anyway. The qB WebUI port stays
+unpublished by design; the e2e torrent test waits on the credentials.
+
+## Deploy flow
+
+Same deployer as every host: `./scripts/deploy.sh frankbook-pro --service
+<svc>` from Dankware. The Mac-side handler (`deploy_frankbook_stack` in
+`scripts/deploy-remote.sh`) pipes unit files + a seed script through
+`podman machine ssh bash -s`, seeds qBittorrent's first-boot config once
+(marker file `qbit-seeded`), restarts the selected unit inside the VM, and
+health-checks its published port on Mac loopback.
+
+## LAN reachability
+
+gvproxy forwards published ports to Mac loopback only. LaunchAgents
+(`local.fwd.*` in `~/Library/LaunchAgents`) run socat forwarders binding the
+LAN IP (192.168.0.112) for arr UIs (9696/8989/7878/8686/8787), the qB WebUI
+(8080, inert until the tunnel is up), and the BitTorrent port 6881 tcp+udp.
+
+## qBittorrent seed (first boot, inside the VM)
+
+- `WebUI\Password` is a **PBKDF2** `@ByteArray(salt:hash)`
+  (PBKDF2-HMAC-SHA512, 100k iterations, 64 bytes) — qB ≥ 4.2 ignores
+  plaintext. The plaintext lives in `/home/core/Containers/qbittorrent/env`
+  (mode 600, VM-local) for Prowlarr wiring.
+- `HostHeaderValidation=false` + `ServerDomains=*`: the socat forwarder
+  preserves the LAN `Host` header, which would otherwise be rejected.
+- `categories.json` pre-creates `Finished Torrents`, `lidarr`, `radarr`,
+  `tv-sonarr` with save_path `/Volumes/COMPLETE/Finished Torrents`.
+- `Session\DefaultSavePath=/Volumes/COMPLETE`,
+  `Session\TempPath=/Volumes/INCOMPLETE/incomplete` (two-disk layout).
+
+# Citations
+
+- Plan: `local://podman-standardization-arr-migration-plan.md` (session 2026-09-01)
+- Units: `frankbook-pro/*/quadlet/*.container`, seam `tests/frankbook_quadlet.bats`
+- Handler: `deploy_frankbook_stack`, `scripts/deploy-remote.sh`