From 06810f861e644f3d3536b650234e6eaadf1402b4 Mon Sep 17 00:00:00 2001
From: Khalid Abdi <xamza2009@gmail.com>
Date: Mon, 29 Jun 2026 21:00:18 +0300
Subject: [PATCH] backend: make docker compose host ports configurable

Mirror the existing POSTGRES_PORT override for the backend, frontend and adminer
host ports (BACKEND_PORT / FRONTEND_PORT / ADMINER_PORT) so a port clash on
`docker compose up -d` can be fixed via .env without editing the compose file.
Documented in .env.example and the README.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md                  |  8 +++++---
 backend/.env.example       |  6 ++++--
 backend/docker-compose.yml | 14 +++++++++++---
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 86c81a1..d8c2883 100644
--- a/README.md
+++ b/README.md
@@ -73,9 +73,11 @@ missing secrets on first start. Then open:
 Prefer to **build from source** (for development)? Use `docker compose up
 --build` instead. Migrations apply automatically on backend start.
 
-> **Port conflict?** If another Postgres holds host port `5432`, set
-> `POSTGRES_PORT` (e.g. `5433`) in `backend/.env`. The app still talks to
-> Postgres internally on `db:5432`; only the published host port changes.
+> **Port conflict?** If host ports `5432`, `4000` or `3000` are already in use,
+> set `POSTGRES_PORT`, `BACKEND_PORT` and/or `FRONTEND_PORT` (e.g. `5433` /
+> `4001` / `3001`) in `backend/.env`. The services still talk to each other on
+> their internal ports (`db:5432`, `backend:4000`); only the published host
+> ports change.
 
 ### Access from other computers (hospital LAN)
 
diff --git a/backend/.env.example b/backend/.env.example
index 9823955..96923e8 100644
--- a/backend/.env.example
+++ b/backend/.env.example
@@ -26,9 +26,11 @@ FRONTEND_URL=http://localhost:3000
 PORT=4000
 NODE_ENV=development
 
-# Host port Postgres is published on by docker compose. Change it if 5432 is
-# already in use on your machine (the app still talks to Postgres internally).
+# Host ports docker compose publishes. Change any that are already in use on
+# this machine (the services still talk to each other on their internal ports).
 POSTGRES_PORT=5432
+BACKEND_PORT=4000
+FRONTEND_PORT=3000
 
 # --- Patient wallet relay -------------------------------------------------
 # The URL baked into the QR a patient scans to import their record. Their phone
diff --git a/backend/docker-compose.yml b/backend/docker-compose.yml
index 96e0079..c4524ee 100644
--- a/backend/docker-compose.yml
+++ b/backend/docker-compose.yml
@@ -25,6 +25,12 @@
 #
 # Optional DB browser (Adminer) lives behind a profile:
 #   docker compose --profile tools up adminer   # http://localhost:8080
+#
+# Host ports are configurable to avoid clashing with software already running on
+# this machine. Override any of them in a .env file (or inline), e.g.:
+#   POSTGRES_PORT=5433  BACKEND_PORT=4001  FRONTEND_PORT=3001  docker compose up -d
+# Only the published host port changes; the services still talk to each other on
+# their internal ports (db:5432, backend:4000).
 
 services:
   db:
@@ -76,7 +82,8 @@ services:
       # Persists uploaded files across restarts/rebuilds.
       - temetro_uploads:/var/lib/temetro/uploads
     ports:
-      - "4000:4000"
+      # Host port is configurable to avoid clashing with an existing service.
+      - "${BACKEND_PORT:-4000}:4000"
 
   frontend:
     image: khalidxv/temetro-frontend:${TEMETRO_VERSION:-latest}
@@ -90,7 +97,8 @@ services:
     depends_on:
       - backend
     ports:
-      - "3000:3000"
+      # Host port is configurable to avoid clashing with an existing service.
+      - "${FRONTEND_PORT:-3000}:3000"
 
   adminer:
     image: adminer:5
@@ -99,7 +107,7 @@ services:
     depends_on:
       - db
     ports:
-      - "8080:8080"
+      - "${ADMINER_PORT:-8080}:8080"
 
 volumes:
   temetro_pgdata: