travel-planner/docs/architecture/deployment.md

Deployment Architecture

Single published port

Production Docker Compose (compose.yml) publishes exactly one host port: edge (Nginx), mapped via APP_HTTPS_PORT (default 443). No other service (api, worker, postgres, redis) defines a Compose ports: mapping — they are reachable only over the internal travel bridge network via their service DNS names. scripts/verify-compose-invariants.mjs (wired into pnpm test:compose) fails the build if this invariant regresses.

TLS

The edge container listens on container port 443 only and requires a certificate and private key mounted at the paths configured by TLS_CERT_FILE/TLS_KEY_FILE (bind-mounted read-only to /run/tls/tls.crt and /run/tls/tls.key). There is no port-80 fallback in this phase.

Internal reachability

• PostgreSQL and Redis are not reachable from the host through Compose-published ports; only containers on the travel network can reach them.
• The API is not reachable from the host directly; all external traffic reaches it through edge's /api/ and /health/ proxy locations.
• The worker process has neither ports nor expose — it accepts no inbound traffic at all.
• Outbound egress from api and worker (e.g. to Mistral, web research, SMTP providers in later phases) remains allowed.

Image tags

TeamCity supplies immutable IMAGE_TAG values (see scripts/teamcity/build-images.sh); latest/floating tags are refused. REGISTRY and IMAGE_TAG together select the exact image digest-equivalent tag deployed to a host.

TeamCity wiring

TeamCity stage	Repository entry point
Validate	scripts/teamcity/validate.sh
Build + Push	scripts/teamcity/build-images.sh
Deploy over SSH	scripts/teamcity/deploy.sh
Post-deploy smoke	scripts/teamcity/smoke.sh
Rollback	scripts/teamcity/rollback.sh

The existing TeamCity project configures these as command-line/SSH build steps; all deployment logic stays in version control, not in TeamCity step configuration.

OIDC configuration (Phase 02+)

api and worker both require OIDC_ISSUER and OIDC_AUDIENCE at startup (validated fail-fast by loadEnvironment, same as DATABASE_URL/REDIS_URL). Neither is a secret — this is a public PKCE client with no client secret. The Angular production bundle bakes OIDC_ISSUER/OIDC_CLIENT_ID in at image build time via docker/edge.Dockerfile build args (sourced from the OIDC_ISSUER/OIDC_CLIENT_ID environment variables passed to docker compose build), not at container runtime, since static frontend assets cannot read server-side environment variables after the fact.

Migrations (Phase 02+)

backend/apps/api/src/migration.ts now runs real, versioned node-pg-migrate migrations from backend/migrations/; the Phase 01 no-op body has been replaced. The container command contract (node backend/dist/apps/api/src/migration.js) is unchanged, so scripts/teamcity/deploy.sh required no changes. Migrations are copied into the travel-api image so docker compose run --rm --no-deps api node backend/dist/apps/api/src/migration.js has everything it needs.