deploy: split compose into base (prod-ready) + dev override

Compose merges list-typed fields like \`ports\` by concatenation, so the
previous prod overlay couldn't clear the base file's host port binding;
the VPS app ended up listening on both port 80 (intranet) AND host port
8800 simultaneously.

Restructured to the conventional dev/prod split:
- docker-compose.yml: no host port — prod-ready by default
- docker-compose.override.yml: dev-only host port binding (auto-loaded
  by \`docker compose up\` locally, skipped when prod uses explicit -f)
- docker-compose.prod.yml: command-port 80 + intranet network only

Production invocation:
  docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -8,24 +8,28 @@ Production:
 
 The Python package is still named `cassandra` and several internal identifiers (cookie names, advisory-lock keys, `CASSANDRA_TOKEN` env var, CSS filename) keep the legacy name on purpose — renaming them would invalidate live sessions / locks / configs for no user benefit. See `app/branding.py` for the brand single-source-of-truth.
 
-## Quick start
+## Quick start (local dev)
 
 ```bash
 cp .env.example .env       # fill in API keys; set CASSANDRA_TOKEN if exposing
 docker compose up --build  # db + app + scheduler + daily backup sidecar
-open http://localhost:8000/
+open http://localhost:8000/  # or whichever CASSANDRA_PORT you set
 ```
 
-## Production (VPS)
+`docker-compose.override.yml` is auto-loaded and adds the host port
+binding so the app is reachable on `localhost`.
 
-Apply the prod overlay so the app has no host port binding and joins the
+## Production (VPS, NPM-fronted)
-existing `intranet` Docker network (where Nginx Proxy Manager lives):
+
+Always invoke with **explicit -f flags** — that way the dev override is
+skipped and the prod overlay (no host port, joins the external
+`intranet` Docker network, uvicorn on port 80) is applied:
 
 ```bash
 docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
 ```
 
-Then point NPM at upstream `readmarkets-app-1:80`.
+Point Nginx Proxy Manager at upstream `readmarkets-app-1:80`.
 
 ## Architecture
 

docker-compose.override.yml

@@ -0,0 +1,9 @@
+# Local-dev overlay. Auto-loaded by `docker compose up` (no -f flags needed),
+# IGNORED on the VPS because prod uses explicit `-f docker-compose.yml -f
+# docker-compose.prod.yml`. Keep dev-only conveniences here so the base
+# `docker-compose.yml` stays prod-ready.
+
+services:
+  app:
+    ports:
+      - "${CASSANDRA_PORT:-8000}:8000"

docker-compose.prod.yml

@@ -13,9 +13,6 @@
 
 services:
   app:
-    # Strip the host port binding from the base file: no public listener
-    # on the VPS, only the intranet bridge.
-    ports: []
     command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80", "--workers", "1"]
     expose:
       - "80"

docker-compose.yml

@@ -48,8 +48,9 @@ services:
         condition: service_healthy
       redis:
         condition: service_healthy
-    ports:
+    # No host port by default — the local-dev override file adds one.
-      - "${CASSANDRA_PORT:-8000}:8000"
+    # See docker-compose.override.yml (dev) and docker-compose.prod.yml
+    # (VPS, NPM-fronted) for the two deployment modes.
 
   scheduler:
     build: .