# EcoKure production readiness runbook

This is the release gate for a customer-controlled pilot. A green application
health check is necessary, not sufficient, for production approval.

For the sign-off record, use [PRODUCTION_LAUNCH_ACCEPTANCE.md](PRODUCTION_LAUNCH_ACCEPTANCE.md).

## 1. Deploy the exact release

Before deploying, run the repository preflight from the release environment:

```bash
python scripts/production_preflight.py
python scripts/production_preflight.py --url "$ECOKURE_BASE_URL"

# In Railway or another deployment shell, prevent a local .env file from
# masking missing deployment variables.
python scripts/production_preflight.py --no-dotenv --url "$ECOKURE_BASE_URL"
```

It prints variable names and pass/fail status only; it never prints secret
values. Do not proceed while either command reports a failure.

- Pin the Git commit, Python version, dependency lock and container/build image.
- Set `FLASK_ENV=production` and generate a unique `SECRET_KEY`.
- Set `ADMIN_KEY` and `API_KEY_HASH_PEPPER` only in the deployment secret
  manager; never in source control, a URL or a frontend bundle.
- All operator APIs use `X-Admin-Key` from a trusted operator environment.
  Production does not accept admin credentials in query strings.
- Set `DATABASE_URL` to the customer-approved PostgreSQL instance.
- Set `LIGHTHOUSE_CORPUS_DATABASE_URL` to a separately permissioned PostgreSQL
  database. The runtime identity must not grant public submission code direct
  write access to this store.
- Set `MAIL_SERVER`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD` (or an app
  password) and `CONTACT_RECIPIENT` so pilot enquiries have a reliable delivery
  path.
- Set `ECOSYSTEM_SSO_CLIENT_SECRET` and `LIGHTHOUSE_REVIEWER_EMAILS`; the
  readiness probe deliberately remains red until reviewer authentication is
  configured.
- Set `ECO_LICENSE_SIGNING_SECRET`, `JARVI3_API_KEY`,
  `ECOSYSTEM_SSO_CLIENT_ID`, `ECOSYSTEM_SSO_REDIRECT_URI` and an HTTPS
  `PUBLIC_BASE_URL` for the signed integration path.

## 2. Probe the service

`GET /healthz` checks process liveness and does not depend on the database.

`GET /readyz` checks the application database, protected corpus store and (in
production mode) required secret, transactional email and reviewer SSO
configuration. A non-200 response must stop traffic promotion. The response
contains only boolean checks and never returns secret values.

```bash
curl -fsS "$ECOKURE_BASE_URL/healthz"
curl -fsS "$ECOKURE_BASE_URL/readyz"
```

## 3. Validate the customer path

1. Create a tenant from a trusted operator environment.
2. Transfer the one-time customer key through the agreed secure channel.
3. Verify the key with the required scope.
4. Run the selected workflow in shadow mode.
5. Create one controlled change event and inspect the impact set.
6. Replay the affected evidence and independently verify the signature.
7. Record reviewer identity, limitations and the written go/no-go decision.

### Lighthouse reviewer access

Configure `LIGHTHOUSE_REVIEWER_EMAILS` as a comma-separated allowlist in the
deployment secret manager. Reviewers use the SSO/MFA path at `/admin/lighthouse`;
do not distribute admin keys in URLs. Keep `X-Admin-Key` restricted to a trusted
operator environment for queue automation and emergency administration.

## 4. Operational gates

- Multi-AZ runtime/database design accepted by the customer.
- Encrypted backup and restore rehearsal completed with recorded RTO/RPO.
- Logs, latency, errors, key use, database health and review queue monitored.
- Operator decisions are retained in an append-only audit trail with actor,
  resource, outcome and timestamp; credentials and secret values are excluded.
- Retrieve that history from `GET /api/admin/audit-events` using the
  `X-Admin-Key` header from a trusted operator environment. Results are bounded
  and can be filtered by `action` or `resource_type`.
- Incident contacts, severity definitions, notification and evidence
  preservation agreed.
- API keys expire, rotate, revoke and are removed during offboarding.
- SBOM, dependency review, threat model and penetration-test position supplied.
- Rollback and Control Pack version pin tested from staging.

## 5. Release truth

The target-environment AWS benchmark is evidence of one measured path. It is
not production customer validation, certification, a Well-Architected review,
or a guarantee that every customer workflow is safe. The customer’s accountable
owners decide whether production use is justified.