diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..6223cce
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,8 @@
+# Copy to .env to override without touching docker-compose.yml.
+# Both are optional - unset values fall back to the defaults below.
+
+# Host port for the frontend (container always listens on 80 internally)
+CLIENT_PORT=5173
+
+# Host port for the backend API (container always listens on 3000 internally)
+SERVER_PORT=3001
diff --git a/.gitignore b/.gitignore
index 93d6dbc..d8a7b80 100644
--- a/.gitignore
+++ b/.gitignore
@@ -71,6 +71,9 @@ web_modules/
 .env.*
 !.env.example
 
+# local Docker Compose overrides
+docker-compose.override.yml
+
 # parcel-bundler cache (https://parceljs.org/)
 .cache
 .parcel-cache
diff --git a/README.md b/README.md
index 1a910d6..0e67b95 100644
--- a/README.md
+++ b/README.md
@@ -239,6 +239,18 @@ To stop:
 docker compose down
 ```
 
+#### Overriding the Ports
+
+If `5173` or `3001` are already in use on your machine, override them without editing `docker-compose.yml`:
+
+```bash
+cp .env.example .env
+# then edit .env, or just export the values inline:
+SERVER_PORT=4001 CLIENT_PORT=8080 docker compose up --build
+```
+
+`docker compose` automatically reads a `.env` file in the project root, so a committed `.env` is never required. Only the host-side port changes - the containers still talk to each other over the internal Docker network regardless of what you choose here.
+
 ### Docker Compose with SSH Key for Git Pull
 
 If your repositories use SSH remotes (for example `git@github.com:...`), mount a private key into the server container:
@@ -339,11 +351,14 @@ cd server && npm run test:coverage
 
 ### Ports
 
-- Backend: `3001` (configured in `server/src/index.ts`)
+- Backend: `3001` (override with the `PORT` env var when running the server directly, e.g. `PORT=4001 npm run dev` in `server/`)
 - Frontend: `5173` (Vite default)
 
+Running via Docker Compose instead? See [Overriding the Ports](#overriding-the-ports) - use `SERVER_PORT`/`CLIENT_PORT` rather than `PORT`, since those control the host-side mapping while the containers keep talking to each other over the internal Docker network.
+
 ### Environment Variables
 
+- Server port: `PORT` (default: `3001`)
 - Frontend API base URL: `VITE_API_BASE_URL` (default: `http://localhost:3001`)
 - Server DB path: `DB_FILE_PATH` (default: `<server cwd>/db.json`)
 - Server upload directory: `UPLOAD_DIR` (default: `<server cwd>/uploads/`)
diff --git a/client/nginx.conf b/client/nginx.conf
index 3bb641c..1fdae79 100644
--- a/client/nginx.conf
+++ b/client/nginx.conf
@@ -6,7 +6,7 @@ server {
   index index.html;
 
   location /api/ {
-    proxy_pass http://server:3001/;
+    proxy_pass http://server:3000/;
     proxy_http_version 1.1;
     proxy_set_header Host $host;
     proxy_set_header X-Real-IP $remote_addr;
diff --git a/docker-compose.yml b/docker-compose.yml
index b043a69..a800116 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -6,12 +6,13 @@ services:
     container_name: git-intelligence-server
     environment:
       NODE_ENV: production
+      PORT: 3000
       DB_FILE_PATH: /data/db.json
       UPLOAD_DIR: /data/uploads
     volumes:
       - server-data:/data
     ports:
-      - '3001:3001'
+      - '${SERVER_PORT:-3001}:3000'
 
   client:
     build:
@@ -23,7 +24,7 @@ services:
     depends_on:
       - server
     ports:
-      - '5173:80'
+      - '${CLIENT_PORT:-5173}:80'
 
 volumes:
   server-data:
diff --git a/server/Dockerfile b/server/Dockerfile
index 585d199..2359a6d 100644
--- a/server/Dockerfile
+++ b/server/Dockerfile
@@ -26,6 +26,7 @@ ENV NODE_ENV=production
 ENV DB_FILE_PATH=/data/db.json
 ENV UPLOAD_DIR=/data/uploads
 
-EXPOSE 3001
+ENV PORT=3000
+EXPOSE 3000
 
 CMD ["node", "dist/index.js"]
diff --git a/server/src/index.ts b/server/src/index.ts
index a16bc01..e420c04 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -9,7 +9,7 @@ import settingsRouter from './routes/settings.js';
 import { errorHandler } from './middleware/errorHandler.js';
 
 const app = express();
-const port = 3001;
+const port = Number(process.env.PORT) || 3001;
 
 // Middleware
 app.use(cors());