igny8/docs/50-DEPLOYMENT/DOCKER-DEPLOYMENT.md

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.