setup setup

PRODUCTION_INIT.md

@@ -0,0 +1,173 @@
+# Production Initialization Guide
+
+This guide explains how to run initialization tasks (Supabase table setup, Neo4j schema, etc.) in production environments.
+
+## Overview
+
+In development, you use `./start.sh` to run initialization tasks. In production (Docker), you have several options:
+
+## Option 1: Automatic Initialization on Startup (Recommended for First Deploy)
+
+Set environment variables to run initialization when the container starts:
+
+```bash
+# In your .env file or docker-compose.yml
+RUN_INIT=true
+INIT_MODE=infra  # or: infra,gais-data or full
+```
+
+Then start normally:
+```bash
+docker compose up --build
+```
+
+The backend container will:
+1. Run the specified initialization tasks
+2. Start the production server
+
+**Note:** This runs init every time the container starts. For subsequent deployments, use Option 2 or 3.
+
+## Option 2: Run Initialization as Separate Service (One-Time)
+
+Use the dedicated init service:
+
+```bash
+# Run infrastructure setup
+docker compose --profile init up init
+
+# Or run multiple tasks
+INIT_MODE=infra,gais-data docker compose --profile init up init
+```
+
+This runs once and exits. The backend service doesn't depend on it, so you can run it independently.
+
+## Option 3: Manual Initialization (Recommended for Updates)
+
+Run initialization tasks manually using the helper script:
+
+```bash
+# On the host machine
+./init-production.sh infra
+
+# Or using Docker Compose directly
+docker compose run --rm backend python3 main.py --mode infra
+```
+
+### Available Initialization Modes
+
+- **`infra`** - Essential setup:
+  - Neo4j schema and constraints
+  - Calendar structure
+  - Supabase storage buckets
+  
+- **`demo-school`** - Creates demo school (KevlarAI)
+  - Usually only needed for development/demo environments
+
+- **`demo-users`** - Creates demo users
+  - Usually only needed for development/demo environments
+
+- **`gais-data`** - Imports GAIS data (Edubase, etc.)
+  - Public school database imports
+  - May be needed in production
+
+- **`full`** - Runs all initialization tasks in order
+  - infra → demo-school → demo-users → gais-data
+
+## Option 4: Run Inside Running Container
+
+If your container is already running:
+
+```bash
+# Execute init command inside running container
+docker compose exec backend python3 main.py --mode infra
+
+# Or use the helper script
+docker compose exec backend ./init-production.sh infra
+```
+
+## Recommended Production Workflow
+
+### First Deployment
+
+1. **Initial Setup:**
+   ```bash
+   # Set in .env or docker-compose.yml
+   RUN_INIT=true
+   INIT_MODE=infra
+   
+   # Start services
+   docker compose up --build
+   ```
+
+2. **Import Data (if needed):**
+   ```bash
+   docker compose exec backend python3 main.py --mode gais-data
+   ```
+
+### Subsequent Deployments
+
+1. **Normal startup (no init):**
+   ```bash
+   # Ensure RUN_INIT is false or not set
+   docker compose up --build
+   ```
+
+2. **Run init only when needed:**
+   ```bash
+   # When schema changes or new buckets needed
+   docker compose exec backend python3 main.py --mode infra
+   ```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RUN_INIT` | `false` | Set to `true` to run initialization on container startup |
+| `INIT_MODE` | `infra` | Comma-separated list of modes: `infra`, `demo-school`, `demo-users`, `gais-data`, or `full` |
+
+## Examples
+
+### Run only infrastructure setup
+```bash
+INIT_MODE=infra docker compose up --build
+```
+
+### Run infrastructure and GAIS data import
+```bash
+INIT_MODE=infra,gais-data docker compose up --build
+```
+
+### Run full initialization (including demo data)
+```bash
+INIT_MODE=full docker compose up --build
+```
+
+### Run init separately before starting backend
+```bash
+# Run init
+INIT_MODE=infra docker compose --profile init up init
+
+# Start backend (init already done)
+docker compose up backend
+```
+
+## Troubleshooting
+
+### Init fails on startup
+If initialization fails, the container will exit. Check logs:
+```bash
+docker compose logs backend
+```
+
+### Need to re-run init
+Simply run the init command again - most tasks are idempotent:
+```bash
+docker compose exec backend python3 main.py --mode infra
+```
+
+### Skip init on startup
+Ensure `RUN_INIT` is not set or is `false`:
+```bash
+RUN_INIT=false docker compose up --build
+```
+