diff --git a/docs/SESSION_HANDOFF_2026-05-22.md b/docs/SESSION_HANDOFF_2026-05-22.md index c949f65..5a45393 100644 --- a/docs/SESSION_HANDOFF_2026-05-22.md +++ b/docs/SESSION_HANDOFF_2026-05-22.md @@ -123,3 +123,51 @@ Recommended sequence: 4. **Document the operator decision tree**: when to use A vs B vs C. All three upgrade approaches are now in production code. The remaining work is mostly closing the install.sh-tenant gap and operator-experience polish. + +--- + +## Session continuation — env-patch + fleet rollout + Phase 6 status + +After the initial Approach C commits, this session also closed the env-patch gap and rolled the new agent out to the whole fleet. + +### Closed gap: env-patch for install.sh tenants + +Commit `bf997e8`: install.sh tenants (`isRegistered=true`, no `encryptedSecrets`) couldn't have their .env's `IMAGE_TAG` updated through Approach C (CCP filters out .env render, tenant keeps existing). Added: + +- Agent: `POST /instance/:slug/env/patch { vars: { KEY: value } }` — in-place .env key patcher in `file.service.ts:patchEnv()`. Preserves comments and key order; appends unknown keys under a "Added by CCP env-patch" comment. +- CCP: `ExecutionDriver.patchEnv()` + `RemoteDriver.patchEnv()` + `LocalDriver.patchEnv()` (mirrors the agent helper). +- `runReleaseUpgrade`: for isRegistered tenants with newImageTag, calls `driver.patchEnv({ IMAGE_TAG: newImageTag })` between writeFiles and composePull. Non-fatal on failure. + +### Fleet rollout: new ccp-agent on all 7 tenants + +All 7 ccp-agents now expose `/files/diff` + `/env/patch`. Preview endpoint returns 200 on every tenant. + +Discovery during rollout: source-installed tenants (soroush, trbh, pridecorner, bnkops) `build:` ccp-agent from local source rather than pulling registry image. So `docker save | docker load` is wasted on them — they need source files updated + local build. Rollout procedure split: + +- Release/release-converted (marcelle, linda, pia): `docker save | docker load` then `up -d --force-recreate ccp-agent`. +- Source (bnkops, soroush, trbh, pridecorner): `git checkout origin/main -- changemaker-control-panel/agent/src/...` then `docker compose --profile ccp-agent build ccp-agent && up -d --force-recreate`. + +### Phase 6 status + +**Code paths all validated via preview** (preview exercises every layer that apply uses, just without the writeFiles+composePull+composeUp side effects). The new `runReleaseUpgrade` runner has been deployed in `ccp-api` on n4 and is reachable via the UI. + +**Apply NOT triggered on a tenant.** Preview against marcelle revealed substantial nginx/configs template drift that would significantly alter live files: + +| file | before | after | +|---|---|---| +| nginx/conf.d/default.conf | 5296 B | 15695 B | +| nginx/conf.d/api.conf | 1996 B | 84 B | +| nginx/conf.d/services.conf | 26133 B | 9434 B | +| configs/pangolin/resources.yml | 3252 B | 1653 B | +| configs/prometheus/prometheus.yml | 1406 B | 644 B | + +These are CCP-templated files that were designed for CCP-provisioned tenants where CCP is authoritative. For install.sh tenants the install.sh-provisioned content differs. Applying would substantially rewrite marcelle's nginx config and risk breaking its public site. + +**Recommended next session: do for nginx/configs templates what Phase 0 did for docker-compose.yml.hbs** — rewrite each templated file to be byte-equivalent to its canonical install.sh-shipped counterpart. Steps: +1. Diff each of the 5 templated files (`*.hbs`) against the canonical at `changemaker.lite/nginx/conf.d/{default,api,services}.conf.template` and `changemaker.lite/configs/{pangolin,prometheus}/...yml`. +2. Update each `.hbs` to match canonical structure (likely use the same `envsubst`-style env-var substitution that install.sh tenants run at startup). +3. Re-render against marcelle/linda/pia and confirm "modified" → "unchanged" for the 5 files. + +After that, apply on marcelle becomes safe and the E2E test can complete. + +The Approach C code itself is production-ready; the gating issue is template sync, which is mechanical.