revamps docs complete

master-docs/50-infra/CI-CD-PIPELINE.md

@@ -0,0 +1,62 @@
+ # CI/CD Pipeline
+ 
+ ## Purpose
+ Document the build-and-deploy sequence using the artifacts present in the repo. No CI config is versioned here; this describes the expected pipeline based on Dockerfiles and compose.
+ 
+ ## Code Locations (exact paths)
+ - Compose stack definition: `docker-compose.app.yml`
+ - Backend image definition: `backend/Dockerfile`
+ - Frontend image definition: `frontend/Dockerfile` (production build via Caddy)
+ - Backend config: `backend/igny8_core/settings.py`
+ 
+ ## High-Level Responsibilities
+ - Build backend and frontend images from repo sources.
+ - Push images to registry (external step, not defined here).
+ - Deploy via `docker-compose.app.yml` consuming those images on the target host/Portainer.
+ 
+ ## Detailed Behavior
+ - Build steps (as indicated in compose comments):
+   - Backend: `docker build -t igny8-backend:latest -f backend/Dockerfile backend`
+   - Frontend app: `docker build -t igny8-frontend-dev:latest -f frontend/Dockerfile.dev frontend`
+   - Marketing: `docker build -t igny8-marketing-dev:latest -f frontend/Dockerfile.marketing.dev frontend`
+   - Sites renderer: `docker build -t igny8-sites-dev:latest -f sites/Dockerfile.dev sites`
+ - Deploy steps:
+   - Ensure external infra stack (Postgres/Redis/network `igny8_net`) is running.
+   - Pull/receive built images on target.
+   - Run `docker compose -f docker-compose.app.yml -p igny8-app up -d`.
+ - Healthcheck: backend service health gated by `/api/v1/system/status/`; frontend depends_on backend health.
+ - No automated migrations are defined in compose; run `python manage.py migrate` inside backend container before switching traffic if schema changes are present.
+ 
+ ## Data Structures / Models Involved (no code)
+ - None; pipeline operates on container images.
+ 
+ ## Execution Flow
+ - CI: build images → (optional tests not defined here) → push to registry.
+ - CD: pull images on host → `docker compose up -d` using new tags → healthcheck ensures backend ready.
+ 
+ ## Cross-Module Interactions
+ - Celery worker/beat use the same backend image; ensure it is rebuilt alongside backend changes.
+ 
+ ## State Transitions (if applicable)
+ - Service rollout occurs when new containers start; existing volumes (code mounts in compose) mean host filesystem is source of truth in current compose.
+ 
+ ## Error Handling
+ - Build failures visible during `docker build`.
+ - Deploy failures captured via Docker/Portainer logs; unhealthy backend blocks dependent services.
+ 
+ ## Tenancy Rules
+ - Not altered by CI/CD; enforced at runtime by application.
+ 
+ ## Billing Rules (if applicable)
+ - None in pipeline.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - Celery beat/worker containers start via compose; ensure images include latest task code.
+ 
+ ## Key Design Considerations
+ - Current compose uses local bind mounts (`/data/app/igny8/...`) which expect code present on host; in an immutable-image pipeline, remove bind mounts and bake code into images instead.
+ - External infra stack separation requires coordination to ensure DB/Redis available during deploy.
+ 
+ ## How Developers Should Work With This Module
+ - If introducing automated CI, codify the build steps above and add migrations/test stages.
+ - When changing service names or ports, update compose and healthcheck references consistently.