chore(docs): update deployment instructions for Docker Compose with host DB/Redis

- Revised `Deployment_Production.md` to clarify usage of `docker-compose.host-db.yml` for running the API with PostgreSQL and Redis on the host.
- Added details on environment variable requirements and updated health check instructions to reflect port changes.
- Improved clarity on deployment methods and removed outdated sections regarding full-stack deployments.

Author: angoca

docker/docker-compose.host-db.yml

@@ -1,8 +1,8 @@
 # Run only the API container, using PostgreSQL and Redis on the host.
 # Use when DB and Redis are already running on the server (e.g. notes_dwh, system Redis).
 #
-# Usage:
-#   docker compose -f docker/docker-compose.host-db.yml up -d --build
+# Usage (from project root; --env-file .env loads .env from project root):
+#   docker compose -f docker/docker-compose.host-db.yml --env-file .env up -d --build
 #
 # Requires .env with DB_* and REDIS_* (DB_HOST/REDIS_HOST are overridden to host.docker.internal).
 

docs/Deployment_Production.md

@@ -228,76 +228,66 @@ redis-cli -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD ping
 
 ## Deployment
 
-### Method 1: Docker Compose v2 (Recommended)
+**Note**: The server uses Docker Compose v2 (plugin), use `docker compose` (not `docker-compose`). On this server, **PostgreSQL (Analytics/Ingestion) and Redis run on the host**, not in containers—so the recommended Docker option is **API only** with `docker-compose.host-db.yml`.
 
-**Note**: The server uses Docker Compose v2 (plugin), use `docker compose` (not `docker-compose`).
+### Method 1: Docker Compose – API only, host DB/Redis (Recommended for this server)
+
+Use when PostgreSQL and Redis already run on the host (e.g. `notes_dwh`, system Redis). Only the API runs in a container; it connects to the host via `host.docker.internal`.
 
 #### Initial Deployment
 
 ```bash
-# Navigate to application directory
 cd /opt/osm-notes-api
 
-# Build and start services
-docker compose -f docker/docker-compose.yml up -d
+# Ensure .env has DB_PASSWORD (use double quotes if password contains #)
+# --env-file .env loads variables from project root (Compose otherwise looks in docker/)
+docker compose -f docker/docker-compose.host-db.yml --env-file .env up -d --build
 
 # Check status
-docker compose -f docker/docker-compose.yml ps
+docker compose -f docker/docker-compose.host-db.yml ps
 
 # View logs
-docker compose -f docker/docker-compose.yml logs -f api
+docker compose -f docker/docker-compose.host-db.yml logs -f api
 ```
 
 #### Verify Deployment
 
 ```bash
-# Health check
+# Health check (port from .env PORT, default 3010)
 curl -H "User-Agent: Monitor/1.0 (ops@example.com)" \
-     http://localhost:3000/health
+     http://localhost:3010/health
 
-# Expected response:
-# {
-#   "status": "healthy",
-#   "timestamp": "...",
-#   "database": { "status": "up", ... },
-#   "redis": { "status": "up", ... }
-# }
-
-# Test API endpoint
-curl -H "User-Agent: TestApp/1.0 (test@example.com)" \
-     http://localhost:3000/notes-api/v1/analytics/global
+# Version headers
+curl -sI -H "User-Agent: Test/1.0 (a@b.com)" http://localhost:3010/health | grep -i x-api
 ```
 
 #### Update Deployment
 
 ```bash
-# Pull latest code
 cd /opt/osm-notes-api
 git pull origin main
 
-# Rebuild and restart
-docker compose -f docker/docker-compose.yml up -d --build
+docker compose -f docker/docker-compose.host-db.yml --env-file .env up -d --build
 
-# Verify
-curl -H "User-Agent: Monitor/1.0 (ops@example.com)" \
-     http://localhost:3000/health
+curl -H "User-Agent: Monitor/1.0 (ops@example.com)" http://localhost:3010/health
 ```
 
-#### API only with host PostgreSQL and Redis
+To remove leftover postgres/redis containers from a previous full-stack run:  
+`docker compose -f docker/docker-compose.host-db.yml down --remove-orphans`
 
-When PostgreSQL and Redis already run on the host (e.g. `notes_dwh`, system Redis), run only the API container and point it at the host:
+Requires Docker 20.10+ (for `host-gateway`). Port mapping: `${PORT:-3010}:3000`.
 
-```bash
-cd /opt/osm-notes-api
+### Alternative: Docker Compose full stack (API + Postgres + Redis in containers)
 
-# Ensure .env has DB_PASSWORD (use double quotes if password contains #)
-# DB_HOST/REDIS_HOST are overridden to host.docker.internal by this compose
+Use only if you want the API, PostgreSQL, and Redis **all in containers** (e.g. testing or a environment without a host DB). Not for this server when Analytics/Ingestion DB and Redis are on the host.
 
-docker compose -f docker/docker-compose.host-db.yml up -d --build
+```bash
+cd /opt/osm-notes-api
+# Requires .env with DB_PASSWORD set (used by the postgres container)
+docker compose -f docker/docker-compose.yml up -d --build
+docker compose -f docker/docker-compose.yml ps
 ```
 
-The API will connect to the host via `host.docker.internal` (requires Docker 20.10+ with `host-gateway`). Port defaults to `${PORT:-3010}:3000`.
-
 ### Method 2: Docker Standalone
 
 ```bash