From b619733a616d17b693893166c97df5652c715d6d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 3 Jun 2026 17:35:50 +0000 Subject: [PATCH] =?UTF-8?q?Add=20HANDOFF.md=20=E2=80=94=20migration=20stat?= =?UTF-8?q?us,=20taxonomy,=20wolf-pair=20open=20item?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Status snapshot at v0.9.7 for continuing in a new session: module status by category, final taxonomy, the module contract/conventions, verification steps, and the open wolf-pair item (awaiting server.py + Dockerfile upload). https://claude.ai/code/session_017eA2qqq9jfF2tNtpUYL8vK --- HANDOFF.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 HANDOFF.md diff --git a/HANDOFF.md b/HANDOFF.md new file mode 100644 index 0000000..a1cf2d2 --- /dev/null +++ b/HANDOFF.md @@ -0,0 +1,112 @@ +# HANDOFF — modular migration status + +**Version:** 0.9.7 · **Branch:** `claude/happy-volta-RPhbD` +**Read also:** `CHANGELOG.md` (per-version detail), `MODULAR.md` (architecture). + +## Where we are + +We're migrating a giant monolithic installer into a **modular system**: +- `setup.sh` — the one dispatcher (menu + run-one). `lib/common.sh` — shared + helpers + the service registry. `services/.sh` — one file per service. +- Run all: `sudo ./setup.sh` (required gate → Caddy offer → category menu loop). + Run one: `sudo ./setup.sh `. List: `./setup.sh --list`. `--version`. +- Every service installs to its own `~/docker//` with its own + `docker-compose.yml` **and a generated `README.md`** (via `write_readme`). +- Nothing is generated/duplicated: a service = one committed file in `services/`. + +The three monolith tiers still exist, frozen as history: +`ubuntu-post-install-{24.04,26.04}.sh` (original, w/ Keycloak), +`*-no-keycloak.sh`, `*-crowdsec.sh` (current "install everything" + glow). +The `-crowdsec.sh` tier is the migration source of truth. + +## Module status + +**Done (16 modules in `services/`):** +| Group | Modules | +|-------|---------| +| base | base, glow | +| homelab | caddy, crowdsec, authelia, homeassistant | +| utilities | filebrowser, ntfy, portainer, uptimekuma, watchtower | +| gaming | wolf, minecraft, js99er | +| backup | backup | + +**Pending — migrate from `ubuntu-post-install-24.04-crowdsec.sh` (find by `# ---- NAME ----`):** +| Target group | Services to migrate | +|------|---------| +| media | jellyfin, emby, audiobookshelf, immich, arm, lyrion | +| cameras | frigate, frigate-notify | +| utilities | actualbudget, mealie, traccar, findmydevice, magicmirror, wg-easy, ddclient | +| (misc) | meshcentral (remote-mgmt server) | + +Also still monolith-only (Phase-1 / system, not yet modularized): SSH config, +Docker install, Samba, VPNs (Tailscale/NetBird/WireGuard), RustDesk, TeamViewer, +MeshCentral agent, UFW. Decide later whether these become `required`/system +modules. + +## Final taxonomy (categories) + +`base` (required) · `homelab` · `utilities` · `media` · `cameras` · `gaming` · +`backup`. Menu order is set in `setup.sh:CATEGORY_ORDER`. Within `homelab`, +`SERVICE_PRIORITY` puts caddy → crowdsec → authelia first. `media`/`cameras` +won't appear in the menu until they have ≥1 module (no empty categories). + +Note: filebrowser/portainer/uptimekuma/watchtower were placed in `utilities` +(weren't in the original taxonomy list) — move if desired by editing their +`register_service ... ...` line. + +## OPEN ITEM — wolf-pair (action needed from you) + +`wolf-pair` (the FQDN device-pairing page for Wolf/Moonlight) was **dropped** +when Wolf was ported, because its source wasn't available. You said you worked +hard on it and will **upload `wolf-pair/server.py` + `wolf-pair/Dockerfile` +(and anything else it needs) in the next chat.** + +To re-add it: create `services/wolf-pair.sh` (group `gaming`) that builds the +wolf-pair container in `~/docker/wolf-pair/`, wires it to reach Wolf, opens its +port, and offers a Caddy block for the pairing FQDN. Wolf's `manage.sh pin` is +the current stopgap. + +## Module contract (for consistency when adding/migrating) + +```bash +#!/bin/bash +register_service "Description" [port] # one line → appears in menu +install_() { + require_docker || return 1 # docker services only + local DIR="$DOCKER_DIR/" + [ "$DRY_RUN" = true ] && { echo "[DRY-RUN] Would create $DIR ..."; return 0; } + mkdir -p "$DIR"; ensure_docker_dir_ownership "$DIR"; cd "$DIR" || return 1 + cat > docker-compose.yml << 'YAML' + ... +YAML + configure_caddy_for_service "Name" "PORT" "subdomain" # optional + write_readme "$DIR" <.sh`, `./setup.sh --list`, +`sudo ./setup.sh --dry-run --unattended ` (must exit 0). + +## Workflow reminders +- Per-version: bump `VERSION`, add a `CHANGELOG.md` entry, commit, push to + `claude/happy-volta-RPhbD`. +- Your loop: build nice standalone `setup-*.sh` elsewhere → upload here → it gets + "massaged" into a `services/.sh` module (wrap in `install_`, use shared + helpers, per-folder + README, register). + +## Suggested next steps +1. Add `wolf-pair` once you upload its files. +2. Migrate **media** batch (jellyfin, emby, audiobookshelf, immich, arm, lyrion) → v0.9.8. +3. Migrate **cameras** (frigate, frigate-notify) → v0.9.9. +4. Migrate remaining **utilities** (actualbudget, mealie, traccar, findmydevice, + magicmirror, wg-easy, ddclient). +5. Decide how Phase-1/system items (VPNs, Samba, remote-access) fit (required vs + their own category).