salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs re-org

Browse Source
This commit is contained in:
IGNY8 VPS (Salman)
2025-12-09 13:26:35 +00:00
parent 4d13a57068
commit 6a4f95c35a
231 changed files with 11353 additions and 31152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/50-DEPLOYMENT/DATABASE-MIGRATIONS.md Normal file
View File

@@ -0,0 +1,61 @@
# Migration Notes
## Purpose
Track significant schema or data migrations, with references to the scripts present in the repo that have been used to adjust data or structure.
## Code Locations (exact paths)
- Migration/utility scripts (repo root `backend/`):
- `verify_migrations.py`, `verify_status_fixes.py`, `verify_taxonomy.py`
- `fix_*` scripts (e.g., `fix_cluster_status.py`, `fix_content_types.py`, `fix_integration_site_url.py`, `fix_sync.py`, `fix_taxonomy_relationships.py`)
- `rename_fields_migration.sql`
- `inject_test_data.py`, `sync_idea_status.py`, `check_recent_keywords.py`, `check_api_response.py`, `diagnose_generate_content.py`
- Django migrations: `backend/igny8_core/**/migrations/` (per app)
## High-Level Responsibilities
- Capture when ad-hoc fixes or manual SQL were required so future migrations can account for existing state.
- Provide guidance on verifying migrations after code changes.
## Detailed Behavior
- Python fix/verify scripts operate against live DBs to patch or validate data (names indicate target domain: clusters/content/integration/taxonomy).
- `rename_fields_migration.sql` suggests a manual SQL rename was performed; ensure corresponding Django migration exists or is applied.
- `verify_*` scripts check consistency after migrations or data changes.
- These scripts are not automatically executed; they are run manually as needed.
## Execution Flow (Recommended)
- Prefer standard Django migrations first: `python manage.py makemigrations && python manage.py migrate`.
- For data issues covered by fix scripts:
- Review script purpose and run in controlled environment (staging) before production.
- Take DB backup before executing manual SQL or fix scripts.
- After applying migrations/fixes, run verify scripts to confirm expected state.
## Cross-Module Interactions
- Scripts touch planner/writer/integration data; impacts automation and billing indirectly if content/status changes alter usage.
## State Transitions (if applicable)
- DB schema changes via migrations; data patches via scripts.
## Error Handling
- Scripts log/print outputs; failures will surface during execution; no centralized handler.
## Tenancy Rules
- All scripts should respect account/site scoping; review code before running to ensure filters exist or add them.
## Billing Rules (if applicable)
- None directly; data corrections may affect content/automation counts but not credit logs.
## Background Tasks / Schedulers (if applicable)
- None; scripts are on-demand.
## Key Design Considerations
- Keep fix/verify scripts version-controlled but treat them as one-off tools; remove or archive obsolete scripts.
- Ensure Django migrations are the source of truth for schema; manual SQL should be mirrored in migrations.
## How Developers Should Work With This Module
- Before running any fix/verify script, read it and constrain to target account/site if possible.
- Add notes here when new manual interventions occur, including date/purpose and scripts used.
## Recent Hardening (Dec 2025)
- Throttling bypass for authenticated users to prevent user-facing 429s.
- AI keys fallback: OpenAI/Runware pulled from system account (`aws-admin`/`default-account`/`default`) or Django settings if tenant key absent.
- Integration settings restricted to system account or developer (`IsSystemAccountOrDeveloper` backend guard, `AdminGuard` frontend).
- DRF default permissions tightened to authenticated + tenant access (`IsAuthenticatedAndActive`, `HasTenantAccess`); public endpoints must override explicitly (e.g., AuthViewSet).

74
docs/50-DEPLOYMENT/DOCKER-DEPLOYMENT.md Normal file
View File

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

72
docs/50-DEPLOYMENT/ENVIRONMENT-SETUP.md Normal file
View File

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