# 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.