docs: record task 2 compose verification

2026-08-04 14:48:20 +02:00
parent 2595d35682
commit 2e67568282
1 changed files with 75 additions and 0 deletions
@@ -0,0 +1,75 @@
+# Task 2 report — portable Compose contract
+
+## Status
+
+Completed. The root Compose file is now a portable two-service base, with explicit local and
+server overrides. Workspace-registry configuration remains generic and continues to require an
+installation-provided Git remote.
+
+## Changed files
+
+- `.env.example` — shared non-secret, generic endpoint and registry examples.
+- `compose.yaml` — portable `core` and `frontend` base, owned `thothii` network, health checks,
+  named settings/Pi/registry/session volumes, and generic external endpoint variables.
+- `deploy/compose.local.yaml` — loopback core/frontend ports, `AUTH_MODE=none`, local
+  installation identity, and non-persistent restart policy.
+- `deploy/compose.server.yaml` — frontend-only configurable host bind, `AUTH_MODE=upstream`,
+  server identity, host-root data/Pi/registry mounts, and restart policy.
+- `deploy/env/local.env.example` and `deploy/env/server.env.example` — safe profile-specific
+  values using `.example.invalid` documentation domains.
+- `scripts/test-default-compose.sh` — default local portable Compose assertion.
+- `scripts/test-unified-compose.sh` — JSON structural assertions for base/local/server plus the
+  required missing-remote failure checks.
+
+## RED evidence
+
+Before changing Compose, `bash scripts/test-unified-compose.sh` exited 1 with:
+
+```text
+Error: forbidden application coupling
+```
+
+The failure was raised by the required assertion while the rendered root config still contained
+the portal-specific networks and host paths.
+
+## GREEN evidence
+
+The following fresh commands completed with exit status 0:
+
+```text
+bash scripts/test-default-compose.sh
+# default Compose contract passed.
+
+bash scripts/test-unified-compose.sh
+# unified Compose contract passed.
+
+bash -lc 'set -a; source deploy/env/local.env.example; set +a; docker compose -f compose.yaml -f deploy/compose.local.yaml config --quiet'
+
+bash -lc 'set -a; source deploy/env/server.env.example; set +a; docker compose -f compose.yaml -f deploy/compose.server.yaml config --quiet'
+
+bash scripts/verify-line-endings.sh
+git diff --check
+```
+
+The two `config --quiet` invocations source only their non-secret profile example so the requested
+commands can validate the required Git-remote interpolation without an operator `.env` file.
+
+## Self-review
+
+- The base renders exactly `core` and `frontend`; it has no portal, Chirone, local-LLM-network, or
+  host-path coupling.
+- Local publishing is loopback-only; server has no core host port and publishes the frontend bind.
+- The core retains outbound access for configured external DWH, vector, Git, embedding, and LLM
+  endpoints; the owned Compose network is private to this stack but is not marked Docker-internal.
+- The structural test validates the exact required service assertion, forbidden-coupling assertion,
+  required base network/volumes, profile port policy, and `THT_WORKSPACE_GIT_REMOTE` failure.
+- All new YAML and shell files were checked by the repository line-ending verifier.
+
+## Commit
+
+`2595d35682a5200b877acb71764b4eb195a39ea4` — `deploy: unify local and server compose stack`
+
+## Concerns
+
+None for Task 2. Git and connector secret transport remains intentionally outside this base/profile
+contract and is addressed by the next scoped task.