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-freight-api/Dockerfile (MODIFIED — pnpm store cache)
• apps/edr-passenger-api/Dockerfile (MODIFIED — prisma generate in /deploy + pnpm store cache)
• apps/edr-payment-api/Dockerfile (MODIFIED — pnpm store cache)
• infrastructure/docker/Dockerfile.web (MODIFIED — pnpm store cache)
• apps/edr-passenger-web/portal/next.config.js (MODIFIED)
• apps/edr-passenger-web/backoffice/next.config.js (MODIFIED)
• DEPLOYMENT.md (MODIFIED)

Backoffice Pages — Completion

19. All backoffice pages are now fully implemented and connected to the API:
    • live/page.tsx — replaced stub with real LiveTrackingPage using liveApi (trips, crowd signals, delay/status stats)
    • notifications/page.tsx — replaced hardcoded mock + broken Table import with real page using notificationsApi (templates list, send form, notification history tab)

Prisma Client Missing After pnpm deploy (Latest)

20. Fixed passenger API crash in Docker (TypeError: Cannot convert undefined or null to object at class-validator IsEnum, triggered by dist/modules/fare-engine/currency.dto.js):
    • Root cause: currency.dto.ts imports the Currency enum (a runtime value) from @prisma/client. The generated Prisma client is an output of prisma generate, not a package in the pnpm store, so pnpm deploy did not copy it into /deploy. At runtime Currency resolved to undefined → @IsEnum(undefined) → Object.entries(undefined) throws at module load.
    • Prisma 6 + pnpm writes the client to node_modules/.pnpm/@prisma+client@.../node_modules/.prisma/client, not root node_modules/.prisma. The old cp rescue in the Dockerfile guarded on [ -d node_modules/.prisma ] (root) which never existed → silently skipped.
    • Fix in apps/edr-passenger-api/Dockerfile: replaced the broken cp with RUN cd /deploy && npm run prisma:generate after pnpm deploy, regenerating the client into the exact runtime-resolve path (/deploy/node_modules/.prisma/client). Safe because deploy has no --prod flag (so the prisma CLI ships) and package.json declares the schema path.
    • Affected 16 passenger-api files importing from @prisma/client; currency.dto.js just loaded first. payment-api unaffected (TypeORM, no Prisma).

pnpm Store Build Cache Fix (Latest)

21. Fixed Docker builds re-downloading all dependencies every pipeline run:
    • Root cause: install steps used --mount=type=cache,id=pnpm,target=/pnpm/store, but nothing set pnpm's store-dir to /pnpm/store. Default store (~/.local/share/pnpm/store) was never under the mount → BuildKit cached an empty dir → full re-download each build. The two web Dockerfiles had the mount but it was dead; the two API Dockerfiles (freight, payment) had no mount at all.
    • Fix: added ENV PNPM_HOME="/pnpm" (+ PATH) to the base stage of all 5 Dockerfiles so the store resolves to /pnpm/store, matching the mount. Added the cache mount to every pnpm install and pnpm deploy step that lacked it.
    • Files: apps/edr-freight-api/Dockerfile, apps/edr-passenger-api/Dockerfile, apps/edr-payment-api/Dockerfile, infrastructure/docker/Dockerfile.web, infrastructure/docker/Dockerfile.passenger-web.
    • Caveat: BuildKit cache mounts live on the runner host; persists only while the same self-hosted runner/builder is reused and not pruned (docker builder prune wipes it).

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