ubuntu-post-install/HANDOFF.md

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/<name>.sh — one file per service.
• Run all: sudo ./setup.sh (required gate → Caddy offer → category menu loop). Run one: sudo ./setup.sh <name>. List: ./setup.sh --list. --version.
• Every service installs to its own ~/docker/<name>/ 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 ... <group> ... 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)

#!/bin/bash
register_service <name> <group> "Description" [port]   # one line → appears in menu
install_<name>() {
    require_docker || return 1                          # docker services only
    local DIR="$DOCKER_DIR/<name>"
    [ "$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" <<MD
    # Name
    ...how to start/stop, access URL, data location...
    MD
    prompt_yn "Start now? (y/n):" "y" S && docker compose up -d
}

Rules: no set -e; don't redefine log_*/colors (in common.sh); drop the monolith's WHIPTAIL_USED/INSTALL_*/check_service_exists wrappers; use prompt_yn/prompt_text; honor DRY_RUN with an early return before any prompt/curl/apt/docker. System (non-docker) modules: see crowdsec/backup.

Verify each: bash -n services/<name>.sh, ./setup.sh --list, sudo ./setup.sh --dry-run --unattended <name> (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/<name>.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).