174 lines
4.2 KiB
Markdown
174 lines
4.2 KiB
Markdown
# 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
|
|
```
|
|
|