# Configuration

The B12 SIS backend is configured through environment variables. This guide covers all available configuration options.

## Environment Variables

### Database Configuration

| Variable | Description | Example |
|----------|-------------|---------|
| `DB_MASTER_DSN` | Primary database connection string | `user:pass@tcp(localhost:3306)/b12_sis?charset=utf8mb4&parseTime=True&loc=Local` |
| `DB_SLAVE_DSN` | Read replica connection (optional) | Same format as master |

!!! note "Read Replicas"
    If `DB_SLAVE_DSN` is not set, all queries use the master connection. Set this for read-heavy workloads.

### Authentication

| Variable | Description | Default |
|----------|-------------|---------|
| `JWT_SECRET` | Secret key for signing JWTs (min 32 chars) | Required |
| `JWT_EXPIRES_IN` | Access token expiration | `24h` |
| `JWT_REFRESH_EXPIRES_IN` | Refresh token expiration | `168h` (7 days) |
| `DEFAULT_PASSWORD` | Default password for new/reset users | `changeMe123!` |

### Server Settings

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | HTTP server port | `8080` |
| `DEV_MODE` | Enable development features | `false` |
| `DEPLOY_AS_JOB` | Run as job scheduler instead of API | `0` |

### AWS S3 Storage

For file uploads (avatars, documents, imports):

| Variable | Description |
|----------|-------------|
| `AWS_ACCESS_KEY_ID` | AWS access key |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key |
| `AWS_REGION` | AWS region (e.g., `ap-southeast-1`) |
| `AWS_BUCKET_NAME` | S3 bucket name |
| `AWS_ENDPOINT` | Custom S3 endpoint (for S3-compatible storage) |

### Canvas LMS Integration

| Variable | Description |
|----------|-------------|
| `CANVAS_API_URL` | Canvas API base URL |
| `CANVAS_API_TOKEN` | Canvas API access token |
| `CANVAS_ACCOUNT_ID` | Canvas root account ID |
| `CANVAS_SYNC_ENABLED` | Enable Canvas sync (`true`/`false`) |

### Email Configuration

| Variable | Description |
|----------|-------------|
| `SMTP_HOST` | SMTP server hostname |
| `SMTP_PORT` | SMTP port |
| `SMTP_USER` | SMTP username |
| `SMTP_PASS` | SMTP password |
| `SMTP_FROM` | Default from email address |

### Rate Limiting

| Variable | Description | Default |
|----------|-------------|---------|
| `RATE_LIMIT_ENABLED` | Enable rate limiting | `true` |
| `RATE_LIMIT_REQUESTS` | Max requests per window | `100` |
| `RATE_LIMIT_WINDOW` | Time window in seconds | `60` |

## Example Configuration

### Development (.env)

```bash
# Database
DB_MASTER_DSN=root:password@tcp(localhost:3306)/b12_sis_dev?charset=utf8mb4&parseTime=True&loc=Local

# Authentication
JWT_SECRET=development-secret-key-at-least-32-characters-long
JWT_EXPIRES_IN=24h
DEFAULT_PASSWORD=dev123

# Server
PORT=8080
DEV_MODE=true
DEPLOY_AS_JOB=0

# AWS (local MinIO for development)
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_REGION=us-east-1
AWS_BUCKET_NAME=b12-dev
AWS_ENDPOINT=http://localhost:9000

# Canvas (development instance)
CANVAS_API_URL=https://canvas-dev.yourschool.edu
CANVAS_API_TOKEN=dev-token
CANVAS_ACCOUNT_ID=1
CANVAS_SYNC_ENABLED=false

# Rate Limiting (disabled for dev)
RATE_LIMIT_ENABLED=false
```

### Production

```bash
# Database (use environment-specific secrets management)
DB_MASTER_DSN=${DB_MASTER_DSN}
DB_SLAVE_DSN=${DB_SLAVE_DSN}

# Authentication
JWT_SECRET=${JWT_SECRET}
JWT_EXPIRES_IN=1h
DEFAULT_PASSWORD=${DEFAULT_PASSWORD}

# Server
PORT=8080
DEV_MODE=false
DEPLOY_AS_JOB=0

# AWS
AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
AWS_REGION=ap-southeast-1
AWS_BUCKET_NAME=b12-production

# Canvas
CANVAS_API_URL=https://canvas.yourschool.edu
CANVAS_API_TOKEN=${CANVAS_API_TOKEN}
CANVAS_ACCOUNT_ID=1
CANVAS_SYNC_ENABLED=true

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60
```

## Multi-tenancy Configuration

The system supports multiple tenants (schools/campuses) through the Team model. Each API request must include:

```http
X-Team-ID: <team-uuid>
```

This header is validated by the `TeamMiddleware` and used to:

1. Filter data to only show records belonging to the team
2. Automatically set `team_id` on newly created records
3. Include child teams in queries (hierarchical structure)

## Academic Session Configuration

Academic sessions represent school years. The current session is set via:

```http
X-Academic-Session-ID: <session-uuid>
```

This affects:

- Attendance records
- Gradebook entries
- Timetable schedules
- Enrollment records

## CORS Configuration

CORS is configured in the middleware. Default settings allow:

- All origins in development mode
- Configured origins in production
- Standard methods: GET, POST, PUT, DELETE, OPTIONS
- Headers: Authorization, Content-Type, X-Team-ID, X-Academic-Session-ID

## Logging Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `LOG_LEVEL` | Log level (debug, info, warn, error) | `info` |
| `LOG_FORMAT` | Output format (json, text) | `json` |

## Security Headers

The API automatically adds security headers:

- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
- `X-XSS-Protection: 1; mode=block`

## Next Steps

- [Quick Start Guide](quickstart.md) - Make your first API calls
- [Authentication](../api/authentication.md) - Learn about the auth system