docs: rename docs/ -> serverAppConfigs-docs/ per system-wide PROJECTNAME-docs convention

All in-repo path references (AGENTS.md, README, old scripts, report artifacts, test code paths) rewritten in the same commit; focused-test map extended for .gitignore, old/scripts/*, dankclaw/comfyui/*, and report/* per this repo's own convention ('add one before committing'). Obsidian wikilinks are title-based and unaffected.
2026-08-28 02:20:06 -07:00
parent 6d4a96a423
commit 5829a0bfe8
140 changed files with 1820 additions and 86 deletions
@@ -0,0 +1,128 @@
+---
+type: guide
+title: Deployment Flow
+description: Service-scoped Git deployment for the two homelab hosts.
+tags:
+  - deployment
+  - operations
+  - git
+timestamp: 2026-09-03
+---
+
+# Deployment Flow
+
+Git is the single source of truth. `scripts/deploy.sh` pushes the committed
+`main` branch, pulls it on one target, and applies only the runtime services
+whose tracked inputs changed. A SearXNG change no longer recreates the
+inference service; an LLM change no longer restarts unrelated containers.
+
+## Workflow
+
+```mermaid
+graph LR
+    A[Edit in this repo] --> B[Run tests]
+    B --> C[Commit main]
+    C --> D[deploy.sh computes plan]
+    D --> E[Push main]
+    E --> F[Target pulls with ff-only]
+    F --> G[deploy-remote.sh dispatches selected services]
+    G --> H[Per-service health check]
+```
+
+1. Edit files locally in this repository.
+2. Run `./tests/run.sh`, then commit the complete change on `main`.
+3. Run `./scripts/deploy.sh <target>`.
+4. The planner maps changed paths to services. Compose YAML is compared by
+   service definition so an edit to one service does not restart its peers.
+5. The target pulls with `git pull --ff-only origin main` and runs the remote
+   dispatcher with the explicit plan.
+6. The dispatcher updates only selected Quadlet, compose, homepage, Caddy, or
+   systemd services and records each successful service revision outside Git.
+
+## Commands
+
+```bash
+./scripts/deploy.sh dankclaw
+./scripts/deploy.sh dankserver
+./scripts/deploy.sh dankclaw --service searxng
+./scripts/deploy.sh dankserver --service frank-default-small
+./scripts/deploy.sh dankclaw --dry-run
+```
+
+`--service` is repeatable and is an explicit retry/override. Without it, the
+planner compares the local `HEAD` to `origin/main`. A documentation-only
+commit produces an empty plan. The remote state directory can also replay a
+service whose earlier deployment failed, but it never expands a plan to a
+service on the other host.
+
+## Service managers
+
+| Service family | Runtime manager | Scope behavior |
+|---|---|---|
+| Dankclaw compose services | `podman-compose -f dankclaw/compose.yaml up -d --no-deps NAME` | Recreates only `NAME`; Caddy is handled separately because it fronts both hosts. |
+| SearXNG, Gluetun, Valkey, OpenWebUI, Pi-hole, Gitea database/server | user Quadlet + `systemctl --user` | Installs the selected unit and restarts only the required dependency-coupled units. Gitea's web proxy is the canonical Caddy compose service. |
+| `frank-default-large` | systemd + `systemctl` | Relinks and restarts only the large inference service; waits up to 20 minutes for `/health`. |
+| `frank-default-small` | systemd + `systemctl` | Relinks and restarts only the small inference service; waits up to 20 minutes for `/health`. |
+| Dankserver media inventory | host-managed bare containers | Compose is inventory only; the scoped deploy does not create duplicate containers. |
+
+The shared chat template maps to the inference service on the selected target.
+The inactive `frank-default-npu` unit is relink-only when explicitly selected;
+it is not restarted by an unrelated large-model deployment.
+
+## Caddy safety
+
+Caddy runs on Dankclaw and fronts both hosts, including Gitea. The former
+standalone `gitea-caddy` Quadlet is retired; the canonical compose `caddy`
+service is now the sole reverse-proxy owner of ports 80/443. A Caddy reload
+failure falls back to a restart of **only** the selected `caddy` container.
+Before deploying, verify that no retired proxy still owns either port.
+
+Homepage files, generated `deployed.js`, the status checker, and the rendered
+Caddyfile are updated only when their service is selected. A media-only
+Dankserver deployment does not touch Dankclaw's proxy or homepage.
+
+## Per-service state
+
+The remote runner writes one revision file per successfully completed service
+to:
+
+```text
+${XDG_STATE_HOME:-~/.local/state}/serverAppConfigs/deploy-state/
+```
+
+The directory is outside the checkout and is never committed. A failed handler
+is not marked successful. On the next ordinary deployment, the runner compares
+the recorded revision with the new checkout and retries only a still-changed
+service. This prevents a failed Caddy or LLM deployment from being silently
+forgotten while avoiding a host-wide restart.
+
+## Targets
+
+| Target | Host | Repository checkout |
+|---|---|---|
+| dankclaw | `dank@dankclaw` (`192.168.0.143`) | `/home/dank/serverAppConfigs` |
+| dankserver | `dank@dankserver` (`192.168.0.235`) | `/home/dank/serverAppConfigs` |
+
+SSH uses the existing key pair. No password is stored or documented in this
+repository. If sudo is needed on a headless target, `FRANK_SUDO_PW` is read
+from the environment and is never written to the repository.
+
+## Tests
+
+Run the full suite before pushing:
+
+```bash
+./tests/run.sh
+```
+
+The deployment seams are in `tests/deployment_scoping.bats` and
+`tests/deployment_flow.bats`. They cover path isolation, compose narrowing,
+Caddy safety, inference isolation, per-service state, and legacy wrapper
+routing. See [[Testing Policy]].
+
+## See Also
+
+- [[Testing Policy]]
+- [LLM deployment](../LLM/deployment.md)
+- [[Caddy]]
+- [[SearXNG]]