setup setup

FIRST_RUN_SETUP.md

@@ -0,0 +1,128 @@
+# First Run Setup Guide
+
+This guide shows how to enable full initialization including demo users and schools on first deployment.
+
+## Quick Start: Full Setup with Demo Data
+
+### Option 1: Using .env file (Recommended)
+
+Add these lines to your `.env` file:
+
+```bash
+RUN_INIT=true
+INIT_MODE=full
+```
+
+Then start:
+```bash
+docker compose up --build
+```
+
+This will run:
+1. ✅ Infrastructure setup (Neo4j schema, calendar, Supabase buckets)
+2. ✅ Demo school creation (KevlarAI)
+3. ✅ Demo users creation
+4. ✅ GAIS data import (Edubase, etc.)
+
+### Option 2: Environment Variable Override
+
+```bash
+RUN_INIT=true INIT_MODE=full docker compose up --build
+```
+
+### Option 3: Custom Combination
+
+If you want infrastructure + demo data but skip GAIS import:
+
+```bash
+# In .env or as environment variable
+RUN_INIT=true
+INIT_MODE=infra,demo-school,demo-users
+```
+
+## Available INIT_MODE Options
+
+| Mode | What It Does |
+|------|-------------|
+| `infra` | Infrastructure only (Neo4j schema, calendar, Supabase buckets) |
+| `demo-school` | Creates demo school (KevlarAI) |
+| `demo-users` | Creates demo users |
+| `gais-data` | Imports GAIS data (Edubase, etc.) |
+| `full` | **All of the above** (infra → demo-school → demo-users → gais-data) |
+| `infra,demo-school,demo-users` | Custom: Infrastructure + demo data (no GAIS) |
+| `infra,gais-data` | Infrastructure + GAIS data (no demo data) |
+
+## Examples
+
+### Full setup with everything (recommended for first run)
+```bash
+RUN_INIT=true
+INIT_MODE=full
+```
+
+### Infrastructure + demo data only (no GAIS import)
+```bash
+RUN_INIT=true
+INIT_MODE=infra,demo-school,demo-users
+```
+
+### Infrastructure only (production, no demo data)
+```bash
+RUN_INIT=true
+INIT_MODE=infra
+```
+
+### Infrastructure + GAIS data (production with public school data)
+```bash
+RUN_INIT=true
+INIT_MODE=infra,gais-data
+```
+
+## After First Run
+
+Once initialization is complete, you can disable automatic initialization for subsequent deployments:
+
+```bash
+# In .env file
+RUN_INIT=false
+```
+
+Or simply remove/comment out the `RUN_INIT` line. The backend will start normally without running initialization tasks.
+
+## Manual Re-initialization
+
+If you need to re-run initialization later:
+
+```bash
+# Run specific mode
+docker compose exec backend python3 main.py --mode infra
+docker compose exec backend python3 main.py --mode demo-school
+docker compose exec backend python3 main.py --mode demo-users
+
+# Or use the helper script
+docker compose exec backend ./init-production.sh full
+```
+
+## Troubleshooting
+
+### Check if initialization ran
+```bash
+docker compose logs backend | grep -i "initialization\|infra\|demo"
+```
+
+### Re-run initialization
+If initialization failed or you need to re-run it:
+```bash
+# Set in .env temporarily
+RUN_INIT=true
+INIT_MODE=full
+
+# Rebuild and start
+docker compose up --build
+```
+
+### Skip initialization on startup
+```bash
+RUN_INIT=false docker compose up --build
+```
+