api/PRODUCTION_INIT.md

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:

# In your .env file or docker-compose.yml
RUN_INIT=true
INIT_MODE=infra  # or: infra,gais-data or full

Then start normally:

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:

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

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

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

   # Set in .env or docker-compose.yml
   RUN_INIT=true
   INIT_MODE=infra
   
   # Start services
   docker compose up --build
   

2. Import Data (if needed):

   docker compose exec backend python3 main.py --mode gais-data
   

Subsequent Deployments

1. Normal startup (no init):

   # Ensure RUN_INIT is false or not set
   docker compose up --build
   

2. Run init only when needed:

   # 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

INIT_MODE=infra docker compose up --build

Run infrastructure and GAIS data import

INIT_MODE=infra,gais-data docker compose up --build

Run full initialization (including demo data)

INIT_MODE=full docker compose up --build

Run init separately before starting backend

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

docker compose logs backend

Need to re-run init

Simply run the init command again - most tasks are idempotent:

docker compose exec backend python3 main.py --mode infra

Skip init on startup

Ensure RUN_INIT is not set or is false:

RUN_INIT=false docker compose up --build