Environments & Secrets

Environments

The platform runs in four environments: development, staging, production, and test. The active environment is set via the pixwel_environment env var.

How secrets are managed

Secrets are stored in AWS SSM Parameter Store and fetched at runtime. Nothing sensitive is committed to git or baked into Docker images.

SSM layout

Path	What
`/platform/development/env`	Full env file for local dev
`/platform/staging/env`	Full env file for staging ECS containers
`/platform/production/env`	Full env file for production ECS containers
`/platform/development/cloudfront_pem`	CloudFront signing key (development)
`/platform/staging/cloudfront_pem`	CloudFront signing key (staging)
`/platform/production/cloudfront_pem`	CloudFront signing key (production)
`/platform/aspera_client_pem`	Aspera JWT signing key (shared across envs)

Individual secrets (mongo URI, OAuth secrets, etc.) are stored at /platform/{environment}/{key} and injected into Lambda functions via api/serverless.yml.

How it works per deployment mode

Local dev (Codespace or laptop with docker-compose)

./install/fetch-secrets.sh development

Fetches:

/platform/development/env → docker/development.env
/platform/development/cloudfront_pem → docker/pems/cloudfront.pem
/platform/aspera_client_pem → docker/pems/aspera.pem

install.sh calls this then copies docker/development.env to .env for docker-compose. docker-compose.yml mounts docker/pems/ into every container at /opt/pixwel/pems. The PHP bootstrap uses those files directly — no SSM calls at container startup, so offline development works after the initial fetch-secrets.sh run. Requires: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY with SSM read access (one-time, for fetch-secrets.sh).

GitHub Actions (CI tests)

test.yml runs ./install/fetch-secrets.sh development before building the API test container.

GitHub Actions (deploy)

deploy.yml runs ./install/fetch-secrets.sh staging or ./install/fetch-secrets.sh production in the deploy jobs. The env file is copied to .env and passed to the ECS task via --env-file.

ECS containers (staging/production)

The container starts with the env file injected at runtime (--env-file). The PHP bootstrap (api/config/bootstrap/environments.php) fetches the signing keys from SSM once per container and caches them to a stable path ($TMPDIR/pixwel-pems); every request after the first reads the cached file. No keys are baked into the image, and there are no SSM calls in the request/response cycle — only the first request (or worker process boot) per container touches SSM.

Lambda (serverless API functions)

Secrets are injected at deploy time from SSM by serverless.yml via ${ssm:/platform/{env}/{key}} references. The PHP bootstrap caches cloudfront_pem / aspera_client_pem the same way as ECS — no runtime SSM calls.

AWS identities & access

Secrets access is controlled by IAM. There are a few distinct identities, by layer:

Where	Identity	Used for
CI — `fetch-secrets.sh` step	`engineering-test-user` (member of the `pixwel-platform-engineering` group) via `secrets.AWS_ACCESS_KEY_ID`	reading SSM on the runner to write the env file + PEMs
CI — serverless deploys	a dedicated serverless-deploy user (hardcoded key id in `deploy.yml`) + `secrets.ENG_AWS_SECRET_ACCESS_KEY`	`serverless deploy`
App inside containers (ECS + CI test containers)	`platform-staging` / `platform-production` (the `aws_key`/`aws_secret` in the env file)	the app’s own AWS calls + the bootstrap’s per-container SSM fetch
Codespaces / local	pass-through `AWS_ACCESS_KEY_ID` from Codespace/host env (typically a `pixwel-platform-engineering` group member)	`fetch-secrets.sh`

SSM read grants live on the pixwel-platform-engineering group policy (for engineers + CI’s test user) and on the per-environment app users (platform-staging, platform-production). When adding a new SSM parameter, make sure the relevant identity is granted ssm:GetParameter on its path — e.g. the group policy currently allows /platform/development/* plus the shared /platform/aspera_client_pem.

Hardening backlog: engineering-test-user is a shared user with a long-lived static key, and CI stores static keys in secrets.AWS_ACCESS_KEY_ID. The modern pattern is GitHub Actions OIDC → sts:AssumeRole (no stored keys) and per-person credentials. Tracked separately.

Updating secrets

To update an env file:

# Fetch current, edit locally, push back
./install/fetch-secrets.sh staging
# edit docker/staging.env
AWS_PROFILE=pixwel aws ssm put-parameter --region us-west-2 \
  --name /platform/staging/env --type SecureString \
  --value "$(cat docker/staging.env)" --overwrite

To update a signing key, update the relevant SSM param directly. The change takes effect on the next container or Lambda cold start.

Adding a new secret

Add to the SSM env file for each environment (/platform/{env}/env)
For Lambda, also add an ${ssm:...} reference in api/serverless.yml
No Dockerfile or git changes needed

​Environments & Secrets

​Environments

​How secrets are managed

​SSM layout

​How it works per deployment mode

​Local dev (Codespace or laptop with docker-compose)

​GitHub Actions (CI tests)

​GitHub Actions (deploy)

​ECS containers (staging/production)

​Lambda (serverless API functions)

​AWS identities & access

​Updating secrets

​Adding a new secret