update deployment docs

DEPLOYMENT.md

@@ -61,15 +61,16 @@ The sync script validates this and fails if missing.
 
 ### Build env files (optional)
 
-Used for build-time variables (example: API URLs for Vite/Next.js), with `export` syntax:
+Used for additional build-time variables (example: Vite API URL for freight web), with `export` syntax:
 
 ```bash
 export FREIGHT_VITE_API_URL=https://freight-api.example.com/api
-export PASSENGER_NEXT_PUBLIC_API_URL=https://passenger-api.example.com
 ```
 
 These are injected into `GITHUB_ENV` during workflow execution.
 
+> **Passenger web:** `NEXT_PUBLIC_API_URL` does **not** need a separate build env file. Place it directly in the service runtime env file (`passenger-portal.env` / `passenger-backoffice.env`) and the sync script will forward it to the build automatically.
+
 ## Docker Compose Port Mapping
 
 `docker-compose.yaml` uses per-service env variables for host/container port mappings:
@@ -97,8 +98,8 @@ The passenger web apps (portal and backoffice) are deployed as **Next.js applica
 | Framework | Vite (SPA) | Next.js (SSR/SSG) |
 | Deployment | Static export + nginx | Node.js server |
 | Dockerfile | `Dockerfile.web` | `Dockerfile.passenger-web` |
-| Final port (container) | 80 (nginx) | 5174/5184 (Next.js) |
-| Build arg | `TURBO_FILTER` | `APP_PACKAGE` + `APP_PATH` + `PORT` |
+| Final port (container) | 80 (nginx) | driven by `PORT` in service `.env` |
+| Build arg | `TURBO_FILTER` | `APP_PACKAGE` + `APP_PATH` + `NEXT_PUBLIC_API_URL` |
 
 ### Build arguments
 
@@ -106,18 +107,27 @@ The Dockerfile accepts the following build args:
 
 - `APP_PACKAGE`: Turbo package filter (e.g., `@edr/passenger-portal`)
 - `APP_PATH`: App directory path (e.g., `apps/edr-passenger-web/portal`)
-- `PORT`: Container port to expose (e.g., `5174`)
-- `NEXT_PUBLIC_API_URL`: API URL visible to browser (e.g., `https://api.example.com`)
+- `NEXT_PUBLIC_API_URL`: API URL visible to browser — sourced from `NEXT_PUBLIC_API_URL` in the service `.env` file
+
+### Port mapping
+
+Both host and container ports are driven by `PORT` in the service env file. The sync script reads `PORT`, exports `PASSENGER_PORTAL_PORT` / `PASSENGER_BACKOFFICE_PORT` to `GITHUB_ENV`, and `docker-compose.yaml` uses those variables for both sides of the mapping:
+
+```
+${PASSENGER_PORTAL_PORT:-5174}:${PASSENGER_PORTAL_PORT:-5174}
+```
+
+This ensures `docker ps` shows `0.0.0.0:<port>-><port>/tcp` with matching ports.
 
 ### Runtime
 
 The final image runs:
 
 ```bash
-node .next/standalone/server.js
+npx next start
 ```
 
-This is the Node.js server provided by Next.js, configured to listen on the `PORT` env var.
+Next.js reads `PORT` from the runtime environment (supplied via `env_file` in docker-compose) to determine which port to listen on.
 
 ## GitHub Actions Deployment Flow
 

checkpoint.md

@@ -35,7 +35,7 @@
 12. Added deployment runbook:
     - `DEPLOYMENT.md`
 
-## Passenger Web Migration to Next.js (Latest)
+## 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`:
@@ -44,17 +44,27 @@
 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, deploys with `.next/standalone` server
-    - Accepts build args: `APP_PACKAGE`, `APP_PATH`, `PORT`, `NEXT_PUBLIC_API_URL`
+    - 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 changed from container:80 to container:5174/5184 (Next.js actual ports)
-    - Updated build args to match new Dockerfile
-    - Changed env var from `PASSENGER_VITE_API_URL` to `PASSENGER_NEXT_PUBLIC_API_URL`
-16. Updated DEPLOYMENT.md:
-    - Added "Passenger Web Docker Configuration" section
-    - Documented differences between freight-web (Vite+nginx) and passenger-web (Next.js+Node.js)
-    - Updated build env file example to use `PASSENGER_NEXT_PUBLIC_API_URL`
+    - 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
 
@@ -84,9 +94,9 @@
 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 now uses Next.js server mode (not static export):
+5. Passenger web uses Next.js server mode (not static export):
    - Requires Node.js at runtime (previously could use pure static hosting)
-   - Deployment must ensure `PASSENGER_NEXT_PUBLIC_API_URL` is set in build env for production deployments
+   - `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