docs re-org

docs/50-DEPLOYMENT/DOCKER-DEPLOYMENT.md

@@ -0,0 +1,74 @@
+ # Deployment Guide
+ 
+ ## Purpose
+ Describe how to deploy the IGNY8 stack using the provided Dockerfiles and `docker-compose.app.yml`, including service wiring and required external dependencies.
+ 
+ ## Code Locations (exact paths)
+ - App compose stack: `docker-compose.app.yml`
+ - Backend image: `backend/Dockerfile`
+ - Frontend image: `frontend/Dockerfile`
+ - Backend settings/env: `backend/igny8_core/settings.py`
+ 
+ ## High-Level Responsibilities
+ - Build images for backend, frontend, marketing, and sites renderer.
+ - Bring up the app stack (backend, frontend, marketing, sites, Celery worker, Celery beat) on the shared external network.
+ - Rely on external infra services (Postgres, Redis) defined outside this repo (referenced in compose comments).
+ 
+ ## Detailed Behavior
+ - Backend container:
+   - Image `igny8-backend:latest` from `backend/Dockerfile` (Python 3.11 slim, installs `requirements.txt`, runs Gunicorn on 8010).
+   - Mounted volumes: `/data/app/igny8/backend` (code), `/data/app/igny8` (shared), `/data/app/logs` (logs).
+   - Env vars for DB/Redis and security flags (USE_SECURE_COOKIES/PROXY, DEBUG, SECRET_KEY).
+   - Healthcheck hits `http://localhost:8010/api/v1/system/status/`.
+ - Frontend container:
+   - Image `igny8-frontend-dev:latest` from `frontend/Dockerfile.dev` (built separately; serves via Vite dev server on 5173 exposed as 8021).
+   - Env `VITE_BACKEND_URL`.
+ - Marketing dev and Sites renderer containers: images `igny8-marketing-dev:latest` and `igny8-sites-dev:latest`, ports 8023→5174 and 8024→5176; Sites mounts `/data/app/igny8/sites` and `/data/app/sites-data`.
+ - Celery worker/beat:
+   - Use `igny8-backend:latest`, commands `celery -A igny8_core worker` and `celery -A igny8_core beat`.
+   - Share same DB/Redis env and code volumes.
+ - Network: `igny8_net` marked `external: true`; compose expects Postgres and Redis running in another stack (`/data/app/docker-compose.yml` per comment).
+ - Ports: backend 8011→8010, frontend 8021→5173, marketing 8023→5174, sites 8024→5176.
+ 
+ ## Data Structures / Models Involved (no code)
+ - Not model-specific; relies on runtime env (Postgres DB, Redis broker).
+ 
+ ## Execution Flow
+ - Build images:
+   - `docker build -t igny8-backend:latest -f backend/Dockerfile backend`
+   - `docker build -t igny8-frontend-dev:latest -f frontend/Dockerfile.dev frontend`
+   - `docker build -t igny8-marketing-dev:latest -f frontend/Dockerfile.marketing.dev frontend`
+   - `docker build -t igny8-sites-dev:latest -f sites/Dockerfile.dev sites`
+ - Ensure external infra stack (Postgres, Redis, network `igny8_net`) is up.
+ - Run: `docker compose -f docker-compose.app.yml -p igny8-app up -d`.
+ - Healthcheck will mark backend healthy before frontend depends_on proceeds.
+ 
+ ## Cross-Module Interactions
+ - Backend depends on Postgres/Redis; Celery worker/beat rely on same env to process automation/AI tasks.
+ - Frontend depends on backend health; sites renderer reads deployed sites from `/data/app/sites-data`.
+ 
+ ## State Transitions (if applicable)
+ - Container lifecycle managed by Docker restart policy (`restart: always`).
+ 
+ ## Error Handling
+ - Backend healthcheck fails if status endpoint not reachable; container marked unhealthy causing depends_on wait.
+ - Gunicorn exit surfaces via Docker logs; no auto-restart beyond Docker restart policy.
+ 
+ ## Tenancy Rules
+ - Enforced in application layer via middleware; deployment does not alter tenancy.
+ 
+ ## Billing Rules (if applicable)
+ - None at deployment layer.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - Celery beat runs schedules (e.g., automation scheduler) using same image and env.
+ 
+ ## Key Design Considerations
+ - Compose uses images (not builds) to avoid accidental rebuilds in Portainer; images must exist beforehand.
+ - External network requirement means infra stack must pre-create `igny8_net` and services.
+ - Backend served by Gunicorn with 4 workers per compose command; adjust via compose if scaling container horizontally.
+ 
+ ## How Developers Should Work With This Module
+ - When changing env vars, update `docker-compose.app.yml` and keep parity with `settings.py`.
+ - For new services (e.g., monitoring), add to compose and attach to `igny8_net`.
+ - Keep healthcheck endpoint stable (`/api/v1/system/status/`) or update compose accordingly.