diff --git a/tools/local-dev/.env b/tools/local-dev/.env
index e7470a6..134bd54 100644
--- a/tools/local-dev/.env
+++ b/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.
diff --git a/tools/local-dev/README.md b/tools/local-dev/README.md
index 0964040..ee78639 100644
--- a/tools/local-dev/README.md
+++ b/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
 
diff --git a/tools/local-dev/docker-compose.yml b/tools/local-dev/docker-compose.yml
index 4dab5b8..ac6d724 100644
--- a/tools/local-dev/docker-compose.yml
+++ b/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: