edr-platform/checkpoint.md

Checkpoint

Major Tasks Completed

1. Docker deployment scaffolded for all 6 apps in the monorepo.
2. Split API images into app-specific Dockerfiles:
   • apps/edr-freight-api/Dockerfile
   • apps/edr-passenger-api/Dockerfile
3. Kept shared Vite/nginx image:
   • infrastructure/docker/Dockerfile.web
   • infrastructure/nginx/spa.conf
4. Updated docker-compose.yaml to run all 6 services (apps only, no Postgres service in compose).
5. Added/updated deployment scripts:
   • scripts/deploy/create-npmrc.sh
   • scripts/deploy/sync-env-from-server.sh
6. Added self-hosted GitHub Actions deployment workflow:
   • Consolidated into one file: .github/workflows/deploy.yml
7. Deployment workflow now:
   • uses a single checkout (prepare job),
   • deploys services via parallel matrix,
   • sets compose project names per branch/environment,
   • passes explicit docker compose --project-name.
8. Environment sync script now:
   • supports branch slug paths,
   • validates each service env file exists,
   • requires PORT in each env file,
   • exports per-service port vars to GITHUB_ENV.
9. docker-compose.yaml now reads per-service ports via variables exported from env sync.
10. Passenger startup flow fixed to run:
    • prisma:generate,
    • prisma:migrate,
    • prisma:seed, before API startup.
11. Passenger seed TypeScript issues fixed in apps/edr-passenger-api/prisma/seed.ts so it compiles under strict checks.
12. Added deployment runbook:
    • DEPLOYMENT.md

Passenger Web Migration to Next.js

13. Passenger web apps migrated from Vite/SPA to Next.js:
    • Updated apps/edr-passenger-web/portal/next.config.js and apps/edr-passenger-web/backoffice/next.config.js:
      • Removed output: 'export' to enable server mode
      • Preserved transpilePackages for @edr/* shared packages
14. Created dedicated Next.js Dockerfile:
    • infrastructure/docker/Dockerfile.passenger-web
    • Uses Node.js server (not nginx) for better Next.js support
    • Builds with turbo, runs npx next start in the final stage
    • Accepts build args: APP_PACKAGE, APP_PATH, NEXT_PUBLIC_API_URL
15. Updated docker-compose.yaml:
    • passenger-portal and passenger-backoffice now use infrastructure/docker/Dockerfile.passenger-web
    • Port mappings are fully dynamic: both host and container ports use ${PASSENGER_PORTAL_PORT} / ${PASSENGER_BACKOFFICE_PORT}, driven by PORT in the service env file
    • NEXT_PUBLIC_API_URL build arg sourced directly from the service env file (no separate build env file needed)
16. Updated DEPLOYMENT.md to reflect all of the above.

Port Mapping Fix (Latest)

17. Fixed passenger web port mapping mismatch (0.0.0.0:8003->5184/tcp):
    • Container port was hardcoded (5174/5184); host port came from PORT in the env file via the sync script
    • Both sides of the mapping now use ${PASSENGER_PORTAL_PORT:-5174} / ${PASSENGER_BACKOFFICE_PORT:-5184}
    • Removed hardcoded PORT build arg from docker-compose.yaml (runtime env_file supplies it to Next.js)

NEXT_PUBLIC_API_URL Build-Time Fix (Latest)

18. Fixed passenger web apps using localhost:4000 instead of the configured API URL:
    • Root cause: NEXT_PUBLIC_* vars are baked into the JS bundle at build time; setting them in the runtime env_file has no effect
    • sync-env-from-server.sh now extracts any NEXT_PUBLIC_* vars from the service .env and writes them to GITHUB_ENV before the build step
    • docker-compose.yaml build arg renamed from PASSENGER_NEXT_PUBLIC_API_URL to NEXT_PUBLIC_API_URL to match the key used in the service env files directly

Key Files to Review

• .github/workflows/deploy.yml
• docker-compose.yaml
• scripts/deploy/sync-env-from-server.sh
• scripts/deploy/create-npmrc.sh
• apps/edr-passenger-api/docker-entrypoint.sh
• apps/edr-passenger-api/prisma/seed.ts
• infrastructure/docker/Dockerfile.passenger-web (NEW)
• apps/edr-passenger-web/portal/next.config.js (MODIFIED)
• apps/edr-passenger-web/backoffice/next.config.js (MODIFIED)
• DEPLOYMENT.md (MODIFIED)

Next Actions

1. Run full CI on all target branches (main, dev, staging) and verify matrix job behavior.
2. Validate server env directory layout matches script expectations:
   • /home/<deploy_user>/environment/edr/<branch-slug>/<project>/...
3. Confirm each service env file includes valid PORT and service-specific runtime vars.
4. Verify branch-specific compose project names produce isolated containers/networks/volumes on runner.
5. Smoke test all 6 deployed services behind real environment URLs.

Open Risks / Notes

1. Passenger seed runs on every container start; confirm this is desired for production-like environments.
2. Prisma warns about package.json#prisma deprecation (Prisma 7 migration pending).
3. Matrix parallelism increases runner load; ensure self-hosted runner capacity is sufficient.
4. Port collisions are prevented by env-driven mapping, but bad env values can still cause runtime conflicts.
5. Passenger web uses Next.js server mode (not static export):
   • Requires Node.js at runtime (previously could use pure static hosting)
   • NEXT_PUBLIC_API_URL must be set in the service env file (passenger-portal.env / passenger-backoffice.env) — the sync script forwards it to the build automatically
   • Each portal/backoffice instance runs its own Node.js process (watch container memory usage)
6. Freight web still uses Vite+nginx (different from passenger web) — maintain both Dockerfiles separately