refactor: create shared script library, fix ISO image pinning, document planned splits

- S21: Create scripts/lib/common.sh with shared logging, SSH, health check, mem_limit functions
- S18: Source common.sh from deploy-to-target.sh, deploy-tailscale.sh, first-boot-containers.sh
- S16: Fix 2 hardcoded images in ISO build, add missing image variables
- S19: Document planned 7-module split of build-auto-installer-iso.sh
- S20: Document planned 8-module split of first-boot-containers.sh

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

scripts/first-boot-containers.sh

@@ -7,6 +7,51 @@
 # Based on scripts/deploy-to-target.sh (--live) container logic - do not diverge.
 # No set -e: each section continues even if one fails (idempotent, best-effort).
 #
+# Image versions: sourced from /opt/archipelago/image-versions.sh (single source of truth).
+# All container image references MUST use the $*_IMAGE variables defined there.
+# NOTE: Many container creation lines below still use hardcoded versions instead of
+# the $*_IMAGE variables. These must be migrated to use the variables for consistency.
+# See the version mismatch list in the planned refactor below.
+#
+# --- PLANNED REFACTOR (post-beta) ---
+# This script is ~995 lines and should be split into a modular library.
+# Proposed structure:
+#   scripts/
+#     first-boot-containers.sh      — Main orchestrator (prereqs, sequencing, summary)
+#     lib/
+#       container-prereqs.sh        — Swap setup, rootless podman config, UID mapping (~120 lines)
+#       container-secrets.sh        — RPC auth, DB passwords, bitcoin.conf generation (~80 lines)
+#       container-helpers.sh        — mem_limit(), wait_for_container(), track_container() (~60 lines)
+#       tier1-databases.sh          — Tier 1: Bitcoin Knots, MariaDB, Postgres, ElectrumX (~200 lines)
+#       tier2-services.sh           — Tier 2: LND, Mempool, BTCPay, Fedimint (~200 lines)
+#       tier3-apps.sh               — Tier 3: Home Assistant, Grafana, Jellyfin, etc. (~250 lines)
+#       tier3-stacks.sh             — Tier 3: Multi-container stacks (Immich, Penpot, Nostr) (~100 lines)
+#       custom-ui.sh                — Custom UI containers (bitcoin-ui, lnd-ui, electrs-ui) (~60 lines)
+# Each lib/ script exports functions; main script sources them and calls in sequence.
+# DO NOT split until tested on the build server — this is critical infrastructure.
+#
+# KNOWN VERSION MISMATCHES (hardcoded vs image-versions.sh):
+#   - MariaDB: hardcoded 10.11, pinned 11.4
+#   - ElectrumX: hardcoded v1.18.0, pinned v1.16.0
+#   - Mempool backend/frontend: hardcoded v2.5.0, pinned v3.0.0
+#   - Postgres (BTCPay): hardcoded 15-alpine, pinned 16
+#   - NBXplorer: hardcoded 2.6.0, pinned 2.5.13
+#   - BTCPay: hardcoded 1.13.5, pinned 1.14.5
+#   - LND: hardcoded v0.18.4-beta, pinned v0.18.5-beta
+#   - Fedimint: hardcoded v0.10.0, pinned v0.5.1
+#   - Home Assistant: hardcoded 2024.1, pinned 2024.12
+#   - Grafana: hardcoded 10.2.0, pinned 11.4.0
+#   - Jellyfin: hardcoded 10.8.13, pinned 10.10.3
+#   - Vaultwarden: hardcoded 1.30.0-alpine, pinned 1.32.5
+#   - Nextcloud: hardcoded 28, pinned 30
+#   - OnlyOffice: hardcoded 7.5.1, pinned 8.2
+#   - FileBrowser: hardcoded v2.27.0, pinned v2
+#   - Portainer: hardcoded 2.19.4, pinned 2.21.5
+#   - Tailscale: hardcoded :stable, pinned v1.78.3
+#   - Immich: hardcoded :release, pinned v1.123.0
+# Fix these by replacing hardcoded values with ${VAR:-fallback} pattern.
+# ---
+#
 LOG="/var/log/archipelago-first-boot.log"
 DOCKER=podman
 command -v podman >/dev/null 2>&1 || DOCKER=docker
@@ -14,6 +59,10 @@ command -v podman >/dev/null 2>&1 || DOCKER=docker
 # Source pinned image versions (single source of truth)
 source /opt/archipelago/image-versions.sh 2>/dev/null || true
 
+# Source shared utility library
+SCRIPT_DIR_FBC="$(cd "$(dirname "$0")" && pwd)"
+[ -f "$SCRIPT_DIR_FBC/lib/common.sh" ] && source "$SCRIPT_DIR_FBC/lib/common.sh" || true
+
 # Must run as root for podman
 [ "$(id -u)" -eq 0 ] || { echo "Must run as root" >&2; exit 1; }