Docker
Local Compose stand-ins for local, development and test. All of them run DynamoDB Local + MinIO from one shared block (docker/compose.aws-emulators.yml); test adds Lambda RIE and development can opt in to Postgres. The standalone admin stack adds @tgmc/admin on port 4400 with a MinIO local-CDN bucket — not AWS CloudFront.
Operations (commands, ports, troubleshooting): docker/README.md
CI/CD matrix: cicd.md
Host .output
Compose reads workspace .output/<sysEnv> and does not rebuild Nuxt inside the image on every up. scripts/docker-compose.mjs maps:
| Stack | SYS_ENV |
Compose file | Image copy |
|---|---|---|---|
| local | local |
docker/docker-compose.local.yml |
Dockerfile.app .output/local |
| dev | development |
docker/docker-compose.dev.yml |
Dockerfile.app .output/development (api + web) |
| test | test |
docker/docker-compose.test.yml |
Dockerfile.lambda .output/test/server |
On build / --build, ensureNitroOutput runs first (SYS_ENV=… npm run build only if server/index.mjs is missing, then prune sharp + .npmrc). Linux images install native deps. .dockerignore allows .output/local|development|test.
Stacks
| Stack | Compose file | SYS_ENV |
Data | App ports |
|---|---|---|---|---|
| Local | docker/docker-compose.local.yml |
local |
DynamoDB Local :8010 + MinIO :4430 (DATA_BACKEND=sqlite opt-in) |
web 4200 |
| Development | docker/docker-compose.dev.yml |
development |
DynamoDB Local :8010 + MinIO :4430 (Postgres opt-in) |
web 4200, api 4100 |
| Local Lambda test | docker/docker-compose.test.yml |
test |
DynamoDB Local :8000 (in-memory) + MinIO :4420 |
lambda-proxy 4300 |
| Admin (standalone) | docker/docker-compose.admin.yml |
n/a | DynamoDB Local :8001 + MinIO :4410 + Postgres :5433 + SQLite |
admin 4400 |
Shared emulators and DATA_BACKEND
docker/compose.aws-emulators.yml defines dynamodb, dynamodb-init, minio, minio-init and an optional dynamodb-admin once; the four stack files include: it (Compose 2.20+) with per-stack defaults in docker/emulators/<stack>.env. Table names default to portfolio-<stack>-{Messages,Posts,Media}, the bucket to portfolio-assets. docker:local, docker:dev and docker:test set MINIO_BUCKET_POLICY=media: only m/ is anonymously readable, so on dynamodb the media URLs (MEDIA_S3_PUBLIC_ENDPOINT/ASSETS_BUCKET/m/…, see media-nuxt § Public URLs) load in the browser like CloudFront serving m/* on AWS, and everything else still needs a presigned URL. docker:admin keeps public (the local CDN), which is a JSON policy that denies pending/*: presigned uploads wait there for complete and are never anonymously readable on any stack. DATA_BACKEND=sqlite|postgres|dynamodb picks the app’s data store (it overrides the SYS_ENV default; see data-stores.md); docker:local and docker:dev default it to dynamodb, so they exercise the same DynamoDB adapters as AWS. Opt in to Postgres with COMPOSE_PROFILES=postgres DATA_BACKEND=postgres npm run docker:dev. On sqlite the media library is local SQLite + files under MEDIA_LOCAL_ROOT=/app/data/media — the ./data bind mount in docker:local, the shared tgmc-dev-media-data volume in docker:dev (on postgres the catalog is in Postgres on DATABASE_URL and only the files are there) — and uploads use local presign mode: a signed PUT to /api/media/_local-s3/pending/<assetId>/<key> on the app (stored privately until complete publishes it), with the objects served at /m/** (media-nuxt). The URL points back at the container that signed it, so web and api need no shared MEDIA_LOCAL_SIGNING_SECRET. Browse the tables with COMPOSE_PROFILES=tools (dynamodb-admin on http://127.0.0.1:8002). Every emulator port binds 127.0.0.1 only. Details and the port map: docker/README.md.
Port 4200 is shared by host npm run dev, docker:local, and docker:dev — run only one of those at a time.
Hostnames: local → tgmc-portfolio.local; docker:dev → tgmc-portfolio.test (avoid *.dev — HSTS-preloaded). Map both to 127.0.0.1. See ssl-setup.md.
Commands (repo root)
npm run docker:build:local
npm run docker:local # DynamoDB Local + MinIO (DATA_BACKEND=sqlite for ./data); exclusive with docker:dev on :4200
npm run docker:local:down
npm run docker:build:dev
npm run docker:dev
npm run docker:dev:down
npm run docker:build:test # ensureNitroOutput(test) then Lambda image
npm run docker:test
npm run docker:test:smoke # media smoke against http://localhost:4300 (token from .data/docker-test-admin-token)
npm run docker:test:down
Media in docker:test: the Lambda gets the DynamoDB Local Media table (TTL on ttl) and a MinIO bucket that is private except m/ (host port 4420, the presign public endpoint; 4410 stays with docker:admin and 4430 with docker:local/docker:dev, so docker:test can run beside any of them). The port variable is now MINIO_API_PORT (it was MINIO_TEST_API_PORT). Materialize runs synchronously (no queue). MinIO is built from source (docker/Dockerfile.minio) because minio/minio is no longer on Docker Hub. Details: docker/README.md.
Docker-only admin (standalone stack)
Blog, contact messages, and a local MinIO CDN stand-in. One admin UI with a database selector (sqlite |
postgres |
dynamodb; DEFAULT_ADMIN_DATABASE defaults to dynamodb). Not part of the public @tgmc/web app. |
cp .env.admin.example .env.admin # set ADMIN_TOKEN (openssl rand -hex 32; weak tokens are refused)
npm run docker:admin
npm run docker:admin:down
Open http://127.0.0.1:4400/admin. See docs/web/features/admin.md.
Admin DAM (/admin/media) uses local SQLite/FS under MEDIA_LOCAL_ROOT (Compose volume, served by the admin at /m/**) or forwards to web when MEDIA_API_URL is set. The media drawer’s Used by links open on NUXT_PUBLIC_SITE_URL, else on MEDIA_API_URL’s origin only (set per request by the admin server; set NUXT_PUBLIC_SITE_URL so no API origin reaches the browser); with neither they show as text. docker-compose.admin.yml defaults NUXT_PUBLIC_SITE_URL to the docker:dev web as the host maps it (SITE_URL, else http://tgmc-portfolio.test:4200, as in docker-compose.dev.yml), so a forward-mode MEDIA_API_URL=http://web:… never becomes the link origin; set it in .env.admin for another site. Env: .env.admin.example (ADMIN_TOKEN, MEDIA_*). Previews: admin.md § Local media library.
When it forwards, set MEDIA_PRESANITIZE_SECRET in .env.admin to the value of the target’s GitHub Environment secret: the admin then signs the PDFs and MP4s it already sanitized (media-nuxt § Admin preSanitized signature). Test and production use different values, so keep one .env.admin per target (for example .env.admin.test / .env.admin.production, copied to .env.admin before npm run docker:admin), and a test secret can never sign for production. Without it the admin sends no signature; the web stores the upload and, on Lambda, logs presanitize.unsigned (or presanitize.no_key). docker:test passes MEDIA_PRESANITIZE_SECRET / _PREVIOUS from .env.test to its Lambda container.
npm run sam:build is still required to stage infra/sam/.aws-sam/build-src for SAM deploys; Compose test images copy .output/test directly.
Docker ↔ AWS
| Concern | Compose local | Compose dev | Compose test | AWS SAM |
|---|---|---|---|---|
| Data | DynamoDB Local (SQLite opt-in) | DynamoDB Local (Postgres opt-in) | DynamoDB Local (in-memory) | DynamoDB tables |
| App | Nitro node-server |
Nitro node-server (web + api) |
Nitro aws_lambda + RIE |
Lambda + HTTP API |
| Assets | MinIO (m/ public) + web static |
MinIO (m/ public) + web static |
MinIO (m/ public); static staged only (infra/sam/.aws-sam/build-src/public) |
Private S3 + CloudFront |
Images: Node 24 bookworm. Local/dev web/api share docker/Dockerfile.app (COPY .output/${SYS_ENV} → /app/.output). HEALTHCHECK --start-period is a literal 30s (BuildKit does not expand ARG there). Compose healthchecks use HTTPS curl -fkS when HTTPS=1.