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