hyb-oa/.trellis/spec/hyb-oa/deployment-trialrun.md

Deployment / Trial Run

Public OA Boundary

Public OA is quasi-production. Deployments, remote config changes and live data operations require explicit approval and evidence.

Rules

• Use SYNC_ENV=0 bash deploy/trialrun/deploy.sh only when deployment is approved; do not overwrite remote .env.
• When server/src/config.js reads a new environment key, add the same key to deploy/trialrun/.env.example before deployment; deploy/trialrun/deploy.sh runs node deploy/trialrun/validate-env-contract.js at step 0 and must fail if the example contract drifts.
• After deployment, report commit hash, /ready, public smoke results and whether the user can test.
• Real business writes are manual unless an Issue explicitly authorizes a controlled test write.
• Do not execute real payments, import bank statements, connect payment providers or write ERP without a separate approved Issue.

Scenario: Deployment Env Contract

1. Scope / Trigger

• Trigger: any backend config, deployment compose, or trialrun env wiring change.
• Purpose: prevent deploy-time surprises where local code compiles but the deployment contract rejects the release or silently misses a runtime default.

2. Signatures

• Command: node deploy/trialrun/validate-env-contract.js
• Deployment entry: SYNC_ENV=0 bash deploy/trialrun/deploy.sh
• Contract sources:
  • server/src/config.js
  • deploy/trialrun/.env.example
  • deploy/trialrun/docker-compose.yml

3. Contracts

• Every process.env.KEY or requiredEnv("KEY") in server/src/config.js must be present in deploy/trialrun/.env.example.
• server, worker, and init services must load ./.env through env_file.
• Compose service-level environment overrides are limited to the explicit allowlist in validate-env-contract.js.
• SYNC_ENV=0 is the default public deploy mode; it does not overwrite remote .env.

4. Validation & Error Matrix

• Missing key in .env.example -> validate-env-contract.js exits non-zero.
• Service omits env_file: ./.env -> contract exits non-zero.
• Unauthorized compose override -> contract exits non-zero.
• Remote .env missing -> deploy step 4 exits before migration.

5. Good/Base/Bad Cases

• Good: add EMAIL_LOGIN_CODE_TTL_SECONDS to config.js, document it in .env.example, then run contract validation before deploy.
• Base: code-only feature without env changes still runs the contract gate.
• Bad: add a config key only in config.js; deploy fails at step 0.

6. Tests Required

• Always run node deploy/trialrun/validate-env-contract.js after env-related changes and before public deployment.
• For public deploys, also run or verify /ready, runtime smoke, external deps smoke, public bundle copy scan, and live smoke when credentials exist.

7. Wrong vs Correct

Wrong

# Config key exists only in server/src/config.js.
SYNC_ENV=0 bash deploy/trialrun/deploy.sh

Correct

# Add the key to deploy/trialrun/.env.example first.
node deploy/trialrun/validate-env-contract.js
SYNC_ENV=0 bash deploy/trialrun/deploy.sh