local-dev: parameterize host-port mappings via LOCAL_DEV_*_PORT

The compose stack hard-coded host ports (postgres 5433, redis 6380,
mailpit 8025, gateway REST 8080, gateway gRPC 9090) — fine for a
clean dev machine, painful when those ports collide with other
services on the same host (e.g. a `crowdsec` sitting on
127.0.0.1:8080 or a Prometheus instance on :9090).

Every host-port mapping is now `${LOCAL_DEV_*_PORT:-<old-default>}`,
so the defaults match prior behaviour for everyone and a per-host
override is a single environment variable away. `.env` carries the
overrides as commented-out lines so the customisation surface is
discoverable without grepping the compose file. README's
"Port 8080 already in use" troubleshooting entry now points at the
new variables and the optional `docker-compose.override.yml`
workflow.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

tools/local-dev/.env

@@ -2,6 +2,21 @@
 # file reads these via ${VAR:-} expansions; override per-developer by
 # editing this file (it is committed only with the project defaults).
 
+# Host-port mappings for the stack. The compose file reads each as
+# ${LOCAL_DEV_*_PORT:-<default>}, so leaving them blank or removing
+# the lines below keeps the defaults shown next to each entry. Set
+# a non-default value when the default collides with something else
+# on the host (a system Postgres, a Prometheus instance on :9090,
+# a `crowdsec` sitting on :8080, etc.). The Vite dev server in
+# ui/frontend reads the gateway REST address from
+# VITE_DEV_PROXY_TARGET — point it at the same port (typically via
+# ui/frontend/.env.local).
+#LOCAL_DEV_POSTGRES_PORT=5433
+#LOCAL_DEV_REDIS_PORT=6380
+#LOCAL_DEV_MAILPIT_PORT=8025
+#LOCAL_DEV_GATEWAY_REST_PORT=8080
+#LOCAL_DEV_GATEWAY_GRPC_PORT=9090
+
 # Six-digit decimal accepted by ConfirmEmailCode in addition to the
 # real bcrypt-verified code. Leave the value blank to disable the
 # override and force every login through Mailpit.

tools/local-dev/README.md

@@ -268,10 +268,21 @@ make status         docker compose ps
 - **UI talks to old gateway**: Vite caches `import.meta.env` at boot.
   Restart `pnpm dev` after editing
   `ui/frontend/.env.development.local`.
-- **Port 8080 already in use** — stop the conflicting service or
-  edit the host-side mapping in `docker-compose.yml` (gateway's
-  `ports:` entry) plus the matching `VITE_GATEWAY_BASE_URL` in
-  `ui/frontend/.env.development.local`.
+- **Port 8080 already in use** (or any other host-port in the
+  stack — postgres `5433`, redis `6380`, mailpit `8025`, gateway
+  REST `8080`, gateway gRPC `9090`) — each host-port mapping in
+  `docker-compose.yml` is parameterised through
+  `LOCAL_DEV_*_PORT` with the listed values as defaults. Set a
+  non-conflicting value either by uncommenting / editing the entry
+  in `tools/local-dev/.env`, by exporting the variable in your
+  shell, or by dropping a local override into a
+  `tools/local-dev/docker-compose.override.yml` (compose
+  auto-merges that file and it stays untracked by git). When
+  moving the gateway REST port off `8080`, also point the Vite dev
+  server at the new host port via
+  `VITE_DEV_PROXY_TARGET=http://localhost:<port>` in
+  `ui/frontend/.env.development.local` (or exported per
+  `pnpm dev` invocation).
 
 ## Relationship to other infrastructure
 

tools/local-dev/docker-compose.yml

@@ -29,7 +29,7 @@ services:
       POSTGRES_PASSWORD: galaxy
       POSTGRES_DB: galaxy_backend
     ports:
-      - "5433:5432"
+      - "${LOCAL_DEV_POSTGRES_PORT:-5433}:5432"
     volumes:
       - postgres-data:/var/lib/postgresql/data
     networks:
@@ -54,7 +54,7 @@ services:
       - --save
       - ""
     ports:
-      - "6380:6379"
+      - "${LOCAL_DEV_REDIS_PORT:-6380}:6379"
     networks:
       - galaxy-net
     healthcheck:
@@ -69,7 +69,7 @@ services:
     container_name: galaxy-local-dev-mailpit
     restart: unless-stopped
     ports:
-      - "8025:8025"
+      - "${LOCAL_DEV_MAILPIT_PORT:-8025}:8025"
     networks:
       - galaxy-net
     healthcheck:
@@ -186,11 +186,11 @@ services:
       GATEWAY_AUTHENTICATED_GRPC_ANTI_ABUSE_MESSAGE_CLASS_RATE_LIMIT_REQUESTS: "10000"
       GATEWAY_AUTHENTICATED_GRPC_ANTI_ABUSE_MESSAGE_CLASS_RATE_LIMIT_BURST: "1000"
     ports:
-      - "8080:8080"
+      - "${LOCAL_DEV_GATEWAY_REST_PORT:-8080}:8080"
       # Authenticated EdgeGateway connect-web/gRPC listener. The
       # browser reaches it via the Vite dev proxy in
       # ui/frontend/vite.config.ts.
-      - "9090:9090"
+      - "${LOCAL_DEV_GATEWAY_GRPC_PORT:-9090}:9090"
     volumes:
       - ./keys/gateway-response.pem:/run/secrets/gateway-response.pem:ro
     networks: