From 644bf158cd627e8e0c65f54301f0cd56003c8498 Mon Sep 17 00:00:00 2001
From: Samir Boulahtit <samir.boulahtit@wizard.lu>
Date: Sun, 22 Mar 2026 16:16:29 +0100
Subject: [PATCH] chore: dev/prod Docker compose separation with safety docs

- Add docker-compose.override.yml exposing db/redis ports for local dev
- Remove override from .gitignore so all devs get port mappings
- Use explicit -f in deploy.sh to skip override in production
- Document production safety rule: always use -f on the server

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .gitignore                  |  2 --
 docker-compose.override.yml |  9 +++++++++
 docs/deployment/docker.md   | 27 +++++++++++++++++++++++++++
 scripts/deploy.sh           |  2 +-
 4 files changed, 37 insertions(+), 3 deletions(-)
 create mode 100644 docker-compose.override.yml

diff --git a/.gitignore b/.gitignore
index 86be1765..8e18b447 100644
--- a/.gitignore
+++ b/.gitignore
@@ -156,9 +156,7 @@ uploads/
 __pypackages__/
 
 # Docker
-docker-compose.override.yml
 .dockerignore.local
-*.override.yml
 
 # Deployment & Security
 .build-info
diff --git a/docker-compose.override.yml b/docker-compose.override.yml
new file mode 100644
index 00000000..154a56e3
--- /dev/null
+++ b/docker-compose.override.yml
@@ -0,0 +1,9 @@
+# docker-compose.override.yml — auto-loaded in dev, skipped in prod via explicit -f
+# Exposes database and cache ports to localhost for local development.
+services:
+  db:
+    ports:
+      - "127.0.0.1:5432:5432"
+  redis:
+    ports:
+      - "127.0.0.1:6379:6379"
diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md
index 16b60dc7..2e7cce85 100644
--- a/docs/deployment/docker.md
+++ b/docs/deployment/docker.md
@@ -34,6 +34,33 @@ docker compose logs -f
 make docker-down
 ```
 
+### Dev vs Prod Compose Architecture
+
+The project uses a **compose override** pattern to separate dev and prod concerns:
+
+- **`docker-compose.yml`** — Base config. Services like `db` and `redis` do **not** expose ports to the host (they communicate over internal Docker networks only).
+- **`docker-compose.override.yml`** — Automatically loaded by `docker compose up` in dev. Exposes `db` (5432) and `redis` (6379) to `localhost` so the app can connect from outside Docker.
+- **`scripts/deploy.sh`** — Uses `docker compose -f docker-compose.yml --profile full` which **explicitly skips** the override file.
+
+> **CRITICAL — Production Safety Rule**
+>
+> The `-f docker-compose.yml` flag in `scripts/deploy.sh` is a deliberate security measure that prevents
+> `docker-compose.override.yml` from being loaded in production. This flag **must never be removed**.
+>
+> When running **any** `docker compose` command directly on the production server, you **must** always
+> pass `-f docker-compose.yml` explicitly to avoid accidentally loading the override file:
+>
+> ```bash
+> # CORRECT — on production server
+> docker compose -f docker-compose.yml --profile full up -d
+> docker compose -f docker-compose.yml --profile full logs -f api
+> docker compose -f docker-compose.yml --profile full exec db psql -U orion_user -d orion_db
+>
+> # WRONG — never run bare "docker compose" on production
+> docker compose up -d          # ← loads override, exposes ports!
+> docker compose --profile full up -d   # ← also loads override!
+> ```
+
 ### Current Services
 
 | Service | Port | Profile | Purpose |
diff --git a/scripts/deploy.sh b/scripts/deploy.sh
index 565101f4..90fc4bf6 100755
--- a/scripts/deploy.sh
+++ b/scripts/deploy.sh
@@ -16,7 +16,7 @@
 
 set -euo pipefail
 
-COMPOSE="docker compose --profile full"
+COMPOSE="docker compose -f docker-compose.yml --profile full"
 HEALTH_URL="http://localhost:8001/health"
 HEALTH_RETRIES=12
 HEALTH_INTERVAL=5