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)

# 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

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

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:

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