Infrastructure · Developer Guide · Jun 10, 2026

SSM Secrets — Developer Guide

How services get their secrets now that we've moved from dotenv-vault to AWS SSM Parameter Store, and how to run & manage them locally. Pilot: tradeit-socket-server.

What changed

dotenv-vault → AWS SSM Parameter Store

Secrets are no longer shipped in a .env.vault file or unlocked with a DOTENV_KEY. Instead, the @zengamingx/ssm-bootstrap wrapper fetches /tradeit/<service>/<env>/* from AWS SSM Parameter Store (decrypted) at startup, populates process.env, then launches the app.

In production the EC2 host's instance role reads SSM over IMDSv2 — no secrets baked into the image. Locally, the wrapper uses your own AWS profile.

Before

.env.vault in the repo + DOTENV_KEY on the host / shared with devs.

Now

SSM Parameter Store, fetched at boot via the host role (prod) or your AWS profile (local). No .env.

Local development

Run the app on your machine

Pull develop and remove the old env files

git checkout develop && git pull
rm -f .env*        # old dotenv files, no longer used

Configure your AWS profile (name it tradeit-dev)

Use the access key Ehud sends you privately.

aws configure --profile tradeit-dev
# access key ID + secret · region: eu-west-1 · output: json

Run it
```
npm run dev
```
That's it. The dev script bakes in AWS_PROFILE=tradeit-dev AWS_REGION=eu-west-1 SSM_SERVICE=tradeit-socket-server NODE_ENV=dev, so no manual exports — just keep your profile named tradeit-dev. It pulls the dev secrets from SSM and boots the app.

You also need VPN / network access to the dev & staging MySQL and Redis (unchanged from before). Credentials live in ~/.aws/ — never commit them.

Access model

Who can read/write which environments

Who	dev	staging	production
Devs (`tradeit-dev` IAM group)	read + write	read + write	no access
Admins (Kim, Ehud)	full	full	full
Prod EC2 hosts (instance role)	—	—	read (own service)

Devs get a personal IAM user + access key (issued privately). Prod is fully isolated for devs by SSM path scoping — no prod means not even retrieve. Policy: tradeit-infra/iam/ssm-nonprod-rw.json.

SSM 101 — managing env vars

Path format: /tradeit/<service>/<env>/<KEY> · swap dev ↔ staging

Retrieve one value

aws --profile tradeit-dev ssm get-parameter \
  --name /tradeit/tradeit-socket-server/dev/MYSQL_USER \
  --with-decryption --query Parameter.Value --output text

List all keys for an environment

aws --profile tradeit-dev ssm get-parameters-by-path \
  --path /tradeit/tradeit-socket-server/dev --recursive \
  --query 'Parameters[].Name' --output text

Change an existing value

aws --profile tradeit-dev ssm put-parameter \
  --name /tradeit/tradeit-socket-server/dev/SOME_KEY \
  --value "newvalue" --type SecureString --overwrite

Add a new value

Omit --overwrite so you can't accidentally clobber an existing key.

aws --profile tradeit-dev ssm put-parameter \
  --name /tradeit/tradeit-socket-server/dev/NEW_KEY \
  --value "value" --type SecureString

After changing a value, restart your local app (or redeploy staging) to pick it up — the wrapper reads SSM once at startup.

Troubleshooting

Symptom	Cause / fix
`AccessDenied` on a `production` path	Expected — devs have no prod access. Ask an admin.
`no parameters found under /tradeit/…`	Wrong `SSM_SERVICE`/`NODE_ENV`, or the param tree is empty for that env.
App exits immediately on boot	SSM unreachable or creds missing — the wrapper is fail-fast, there's no `.env` fallback. Check `aws --profile tradeit-dev sts get-caller-identity`.
`could not connect to MySQL/Redis`	Secrets resolved fine, but you're missing VPN/network access to the dev/staging DB & Redis.
Credentials expired / wrong profile	Re-check `~/.aws/credentials` has a `[tradeit-dev]` profile with your key.

Rollout

tradeit-socket-server is the pilot. The same pattern — AWS profile/SSO + /tradeit/<svc>/<env>/* + the @zengamingx/ssm-bootstrap wrapper — is being rolled out to the other ~13 repos. Once you're in the tradeit-dev group, local setup for each new service is the same three steps above.

Generated Jun 10, 2026 · tradeit.gg infrastructure