api/FIRST_RUN_SETUP.md

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:

RUN_INIT=true
INIT_MODE=full

Then start:

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

RUN_INIT=true INIT_MODE=full docker compose up --build

Option 3: Custom Combination

If you want infrastructure + demo data but skip GAIS import:

# 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)

RUN_INIT=true
INIT_MODE=full

Infrastructure + demo data only (no GAIS import)

RUN_INIT=true
INIT_MODE=infra,demo-school,demo-users

Infrastructure only (production, no demo data)

RUN_INIT=true
INIT_MODE=infra

Infrastructure + GAIS data (production with public school data)

RUN_INIT=true
INIT_MODE=infra,gais-data

After First Run

Once initialization is complete, you can disable automatic initialization for subsequent deployments:

# 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:

# 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

docker compose logs backend | grep -i "initialization\|infra\|demo"

Re-run initialization

If initialization failed or you need to re-run it:

# Set in .env temporarily
RUN_INIT=true
INIT_MODE=full

# Rebuild and start
docker compose up --build

Skip initialization on startup

RUN_INIT=false docker compose up --build