Read Docker secrets from a mounted appsettings file, not the environment

[rghvgrv]

Docker now reads every secret from a mounted appsettings.Docker.json. Nothing is passed on the command line, stored in docker-compose.yml, or baked into the image.

How to run it

cp src/SubVora.Api/appsettings.Docker.example.json src/SubVora.Api/appsettings.Docker.json
# edit it: set Jwt:Secret to `openssl rand -base64 48`
docker compose up -d --build

That's the whole thing. No export, no .env.

Why the old way was worse than it looked

docker-compose.yml had Jwt__Secret: "${SUBVORA_JWT_SECRET:?...}". Compose interpolates the whole file on every subcommand, so forgetting the variable didn't just break up — it broke ps, logs and down too. I hit that mid-verification: the stack was running fine and docker compose ps still refused to answer.

Mounted, not copied — and this one was a real leak

COPY src/ src/ in the Dockerfile was baking environment config into the image:

$ docker run --rm --entrypoint sh subvora-api -c 'ls /app/appsettings*.json'
/app/appsettings.Development.json
/app/appsettings.Docker.example.json
/app/appsettings.Docker.json      ← real signing key, in a layer
/app/appsettings.json

Both env files are now in .dockerignore, and the real config arrives only through a read-only bind mount. After:

/app/appsettings.Docker.example.json
/app/appsettings.json      ← ships with blank keys

The image carries no secret. Changing config no longer needs a rebuild either.

Mailpit, and the SMTP bug it exposed

Added a mailpit service so reset codes and already-registered notices are readable at http://localhost:8025.

Which is how I found that local email had never worked. SmtpEmailSender hardcoded SecureSocketOptions.StartTls, and no local mail catcher offers TLS:

System.NotSupportedException: The SMTP server does not support the STARTTLS extension.

Invisible, because #111 moved sends off the request path — it only ever produced a log line.

STARTTLS is now Smtp:UseStartTls, defaulting to true. Deliberately not StartTlsWhenAvailable: a real server carries password reset codes, and silently dropping to plaintext when someone strips the server's advertisement is a downgrade attack. Local configs opt out explicitly.

Verified on the running stack

No environment variables, no .env, secret only in the mount:

health                Healthy
register              202
login -> token        ok (347 chars)
subscriptions         200
dashboard/burn-rate   200
users/me              200
forgot-password       200
mail delivered        3 message(s)   ← both types visible in mailpit

api      Up
db       Up (healthy)
mailpit  Up (healthy)

Migrations and the catalog sync run at start as before.

Application.Tests      28 passed
Infrastructure.Tests   98 passed
Api.Tests              92 passed

Notes

Create the file before the first up. If it's missing, Docker creates a directory at the mount path and the API fails on an empty connection string. Called out in the README and in a compose comment.

This pattern is for local Docker. Deployed environments should still inject config from the platform or a vault — CLAUDE.md still says so, and appsettings.json still ships its keys blank so the app fails fast rather than starting with an empty signing key.

The example's placeholder carries an inline pragma: allowlist secret so the scanner doesn't flag the template on every future baseline regeneration.