cc-ci-orchestrator/cc-ci-plan/plan-prefer-env-over-compose-overlay.md

# Sub-plan — prefer upstream env-parameterization over cc-ci compose overlays

**Status:** QUEUED — a policy + a set of recipe-PR / harness follow-ups. Picks up as near-term Phase-2
units (no phase-pause). **Owner:** Builder + Adversary loops. **This file:**
`/srv/cc-ci/cc-ci-plan/plan-prefer-env-over-compose-overlay.md`
**Codifies:** the `plan.md §9` guardrail "Don't fork the recipe's compose — parameterize upstream,
tune via env."

---

## 0. Principle (operator, 2026-05-30)

**A cc-ci-authored compose file/overlay must be avoided wherever possible** — every extra
`compose.*.yml` we layer via `COMPOSE_FILE` is a private fork of the deployment that can **drift from
the recipe users actually run**, so we'd stop testing what ships. Two strictly-preferred alternatives:

1. **Need a value tuned for cc-ci's env (e.g. a longer healthcheck `start_period`)** → open an
   **upstream recipe PR** that exposes it as an **env var** (current value as the default in
   `env.sample`), e.g. `APP_START_PERIOD`. cc-ci then sets that env in the app `.env` (via
   `recipe_meta` `EXTRA_ENV`) — **no new compose**. Bonus: real operators on slow hosts get the same
   knob.
2. **Need a custom compose only to make the UPGRADE tier work from an older base version** (a
   since-removed image tag, or an overlay the old version predates) → **prefer declaring that older
   version not-testable under this CI env** (record it + skip/scope that crossover) over authoring a
   custom compose for it.

A cc-ci compose overlay is a **last resort** only when neither works; it must be Adversary-confirmed
non-drifting and paired with the upstream-env PR that will obsolete it.

## 1. The current debt to migrate (3 overlays)

- **ghost `compose.ccci-health.yml`** (app `start_period: 900s`) — the fresh-DB MySQL migration
  (~6–9 min) exceeds the recipe's `start_period: 1m` → swarm kills it mid-migration → `migrations_lock`
  deadlock.
- **discourse `compose.ccci-health.yml`** (app `start_period: 1200s` + image re-pin
  `bitnami/discourse:3.3.1`→`bitnamilegacy/discourse:3.3.1` on app+sidekiq) — Rails cold boot 15–25 min
  exceeds the recipe's `start_period: 5m`; the image re-pin is to make the **old base version**
  deployable after Docker Hub dropped the `bitnami/discourse` tags.
- **mumble `compose.host-ports.yml`** — a copy of the *upstream* host-ports overlay, provided only so
  the **older base version (0.2.0+)** that predates it can resolve `COMPOSE_FILE`. (The current version
  ships it natively — that part is fine and stays.)

## 2. Definition of Done (Adversary cold-verifies)

- [ ] **E1 — ghost: `start_period` env PR.** Recipe PR to ghost exposing the app healthcheck
      `start_period` as an env var (e.g. `APP_START_PERIOD`), **default = the current recipe value** in
      `env.sample` (no behavior change for existing users). Verified green on cc-ci (the recipe-PR
      dogfood). Then cc-ci sets `APP_START_PERIOD` via `recipe_meta` `EXTRA_ENV` and **removes
      `tests/ghost/compose.ccci-health.yml` + its `COMPOSE_FILE`/`install_steps` wiring** — full ghost
      suite still green (install migration completes, no deadlock).
- [ ] **E2 — discourse: `start_period` env PR.** Same pattern for discourse's app `start_period`;
      remove the `start_period` half of `compose.ccci-health.yml` once CI tunes it by env.
- [ ] **E3 — discourse old-base image re-pin → declare untestable instead.** Do NOT keep the
      `bitnami→bitnamilegacy` re-pin in a cc-ci compose. Either (a) the recipe PR re-pins the image
      upstream (if that's the genuine recipe fix), OR (b) **declare the old base version not-testable
      under cc-ci** (its image is gone from the registry) and scope the upgrade crossover accordingly
      — recorded in `DECISIONS.md`. Remove the re-pin from any cc-ci compose.
- [ ] **E4 — mumble old-base host-ports → declare untestable instead.** Drop the cc-ci copy of
      `compose.host-ports.yml`; for the old base that predates the upstream overlay, **declare that
      version not-testable under cc-ci's on-host port requirement** rather than shipping a copy. The
      current version (ships the overlay natively) tests normally.
- [ ] **E5 — No cc-ci compose overlays remain** (`tests/**/compose.*.yml` that cc-ci authored/copied
      are gone), OR any that genuinely cannot be replaced is Adversary-justified + paired with a filed
      upstream-env PR. The guardrail (`plan.md §9`) holds going forward.
- [ ] **E6 — No test weakened.** Every affected recipe's full suite still passes with real assertions
      + real healthcheck gating; the only change is *how* the value is supplied (env, not a forked
      compose) or that an un-runnable old crossover is honestly skipped — Adversary cold-verified.

## 3. Notes / guardrails
- Env PRs follow the standard recipe-PR rule: "working" only when cc-ci verifies the full suite green
  (`/recipe-upgrade`'s `!testme`-on-PR path), operator-merged. Mirrors the recipe-robustness PR pattern
  (lasuite-drive collabora, plausible Q4.7b, immich).
- **Declaring a version untestable is a first-class, honest outcome** — record which version + why
  (registry tag gone / predates a required overlay) in `DECISIONS.md`; it is NOT a test weakening.
- Until an env PR is merged upstream, cc-ci may need the recipe-PR *branch* (via `SRC`+`REF`) to test
  green — that's fine (it's the recipe under test), unlike a private cc-ci compose fork.