docs re-org

docs/50-DEPLOYMENT/ENVIRONMENT-SETUP.md

@@ -0,0 +1,72 @@
+ # Environment Setup
+ 
+ ## Purpose
+ Outline required runtime dependencies, environment variables, and local setup steps derived from the codebase configuration.
+ 
+ ## Code Locations (exact paths)
+ - Django settings/env: `backend/igny8_core/settings.py`
+ - Backend dependencies: `backend/requirements.txt`
+ - Backend image provisioning: `backend/Dockerfile`
+ - Frontend env/build: `frontend/Dockerfile`, `frontend/package.json`, `frontend/vite.config.ts`
+ - Compose stack env: `docker-compose.app.yml`
+ 
+ ## High-Level Responsibilities
+ - Provide prerequisites for backend (Python 3.11, Postgres, Redis) and frontend (Node 18).
+ - Enumerate environment variables consumed by backend and compose files.
+ - Describe local or containerized setup flows.
+ 
+ ## Detailed Behavior
+ - Backend settings require:
+   - `SECRET_KEY`, `DEBUG`, `USE_SECURE_COOKIES`, `USE_SECURE_PROXY_HEADER`.
+   - Database: `DATABASE_URL` or `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_PORT`; falls back to SQLite in DEBUG if none provided.
+   - Redis/Celery: `CELERY_BROKER_URL`, `CELERY_RESULT_BACKEND` default to `redis://{REDIS_HOST}:{REDIS_PORT}/0`.
+   - JWT: `JWT_SECRET_KEY`, expiry defaults (15m access, 30d refresh).
+   - CORS: allowed origins include local ports (5173/5174/5176/8024) and `app.igny8.com`.
+   - Stripe/PayPal keys optional (`STRIPE_PUBLIC_KEY`, `STRIPE_SECRET_KEY`, `PAYPAL_*`).
+ - Backend Dockerfile installs system deps (gcc, libpq-dev) and pip installs `requirements.txt`; runs `collectstatic` (best-effort).
+ - Frontend expects `VITE_BACKEND_URL` (compose sets to `https://api.igny8.com/api`); build via `npm install` then `npm run build` (Dockerfile).
+ - Compose injects DB/Redis env to backend/worker/beat and secure cookie/proxy flags for production use.
+ 
+ ## Data Structures / Models Involved (no code)
+ - Not model-specific; environment affects DB connections, auth, CORS, Celery, billing keys.
+ 
+ ## Execution Flow
+ - Local (backend):
+   - `python -m venv .venv && source .venv/bin/activate`
+   - `pip install -r backend/requirements.txt`
+   - Set env vars (DB/REDIS/JWT/CORS/SECRET_KEY).
+   - `python backend/manage.py migrate` then `python backend/manage.py runserver 8010`.
+ - Local (frontend):
+   - `npm install` in `frontend/`
+   - Set `VITE_BACKEND_URL`
+   - `npm run dev -- --host --port 5173`
+ - Containerized:
+   - Build images per Dockerfiles; run `docker compose -f docker-compose.app.yml up -d` with external Postgres/Redis and network `igny8_net`.
+ 
+ ## Cross-Module Interactions
+ - Celery uses same Redis host/port as defined in env; automation tasks rely on this.
+ - CORS/secure cookie flags must align with frontend host to allow auth.
+ 
+ ## State Transitions (if applicable)
+ - `DEBUG` toggles throttling bypass (`IGNY8_DEBUG_THROTTLE`) and SQLite fallback.
+ 
+ ## Error Handling
+ - Missing DB env → falls back to SQLite in DEBUG; in prod must set Postgres vars.
+ - Healthcheck in compose will fail if env misconfigured and backend cannot start.
+ 
+ ## Tenancy Rules
+ - Unchanged by env; account context enforced in middleware once app runs.
+ 
+ ## Billing Rules (if applicable)
+ - Stripe/PayPal keys optional; without them payment flows are disabled/pending.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - Celery broker/backend must be reachable; worker/beat require the same env set.
+ 
+ ## Key Design Considerations
+ - Prefer Postgres in all shared/test/prod; SQLite only for local development.
+ - Keep SECRET_KEY/JWT keys distinct and secret in production.
+ 
+ ## How Developers Should Work With This Module
+ - Add new env variables in `settings.py` with safe defaults; document in this file.
+ - Mirror envs in compose and deployment systems (Portainer/CI) to avoid drift.