Environments

The platform runs in four environments. The same code and the same images run in each; they differ only in environment variables and Helm values.

Environment	Where	Data	How changes arrive
Development	Your own machine	Synthetic, local	You run it
Test	Shared test deployment: public portal eservices.pamodzi.co.zm, back office admin.pamodzi.co.zm	Synthetic and demo data only	Deployed only when the product owner asks
Staging	Government servers, GSB RKE2 cluster gsb-stg	As production requires	Images promoted by digest
Production	Government servers, GSB RKE2 cluster production	Live	Only by promotion from staging, with approvals

Development

• Database. PostgreSQL 18 with PostGIS on localhost:5433, data kept in the workspace's .pgdata/ folder. Never

  point local tools at a remote database.

• Integration tests create a fresh, throwaway database for each test file on the local server, enable PostGIS, and

  load the real application. Both schema modes must pass: the schema built from the models, and the schema built from the migrations (TEST_SCHEMA=migrations, as CI runs it).

• End-to-end tests run in the e2e kit, which drops and re-creates its own database (zcm_e2e) on every run and uses

  the provider test doubles. See End-to-end testing.

• Configuration comes from your local environment file, which is never committed. The repository's .env.example

  documents every variable with placeholder values; npm run check:env fails when the code reads a variable that is not documented there or in the Helm chart.

npm test                                         # unit tests, no database
npm run test:integration                         # one throwaway database per test file
TEST_SCHEMA=migrations npm run test:integration  # the same, schema from migrations

Test

The shared test deployment is for demonstrations and product-owner review.

• It runs as a federated estate: the national hub (the public portal and the hub back office) and one back office per

  MDA, each with its own API and database, generated from the estate description.

• It uses the real GSB test tenants of ZamPay and ZamPass, not production ones and not the e2e test doubles.
• Deploy to it only when the product owner asks.
• Never use real citizen data.

Staging

Staging runs on the government's GSB RKE2 cluster gsb-stg, on the same infrastructure as production.

• The Helm chart deploy/helm/gsb-eservices is installed with the staging overlays (values-staging.yaml,

  values-gsb-rke2.yaml, values-gsb-rke2-stg.yaml).

• Images are never rebuilt for staging. The Promote workflow, which a release manager approves, copies the built image

  by digest from the government's test registry (Harbor, used by the GSB cluster gsb-tst) to the staging registry, and checks that the digest in the target is the same.

• Test and staging use provider sandboxes or stubs until real credentials are issued.

Production

Production runs on the GSB RKE2 cluster production.

• Changes reach production only by promotion from staging, through a protected workflow that needs two reviewers.

  There are no direct deployments.

• Production deploys by digest, so the release records exactly which image runs.
• Production overlays are values-production-dc1.yaml, values-gsb-rke2.yaml and values-gsb-rke2-prod.yaml.

Configuration, not code branches

• An environment differs from another only through environment variables and Helm values. Never add

  if (environment === ...) branches to the code.

• The estate (deploy/estate/estate.yaml) records every MDA and where it runs: hosted on the hub, on its own node, or

  external. npm run estate:render generates each instance's values, deployment definitions and a checklist of the secrets it needs (names only). Never edit the generated files.

• The same codebase runs as PLATFORM_ROLE=combined, hub or node; the role is configuration too.

Secrets and development keys

• Secrets come only from the environment or the secret store. They never appear in the repository, in Helm values

  files, in images or in logs.

• Production refuses development keys. In production the API will not start when a required secret holds a

  placeholder or development value; it names the variable, never the value. The development certificate authority used to seal documents locally is refused when NODE_ENV=production.

• Never open, copy or quote credential files, and never paste a secret into a ticket, chat or commit. If a value is

  exposed, it must be rotated.

Moving a change through the environments

1. Develop and test locally: unit tests, integration tests in both schema modes, the guard checks

   (check:mda, check:modules, check:env), and the service's e2e journey.

2. Merge after review. CI builds the images.
3. Deploy to the shared test deployment when the product owner asks, for review and demonstration.
4. Promote the same images by digest to staging, with a release manager's approval.
5. Promote to production with two reviewers' approval.

Never push or deploy without the owner's approval.