Production Docker Deployment Runbook

This runbook guides system administrators through deploying YeneSchool into production using the official Docker Compose deployment stack.

1. Prerequisites

Before starting, ensure the host server satisfies these minimum requirements:

• Operating System: Ubuntu 22.04 LTS, Debian 12, or AlmaLinux 9 (64-bit).
• Docker Engine: Version 24.0+ installed and running.
• Docker Compose: Plugin version v2.20+ (docker compose version).
• Hardware: Minimum 4 vCPUs, 16 GB RAM, and 50 GB available SSD disk space.
• Firewall: Ports 80 (HTTP), 443 (HTTPS), and 22 (SSH) accessible.

2. Environment Configuration

Clone the repository and copy the production environment template:

git clone https://github.com/your-org/YeneSchool-School-Management-System.git
cd YeneSchool-School-Management-System

# Copy production environment template
cp .env.example .env

Edit .env and configure production secrets:

# Database Credentials
DB_USER=yene_admin
DB_PASSWORD=YOUR_STRONG_RANDOM_PASSWORD_HERE
DB_NAME=yeneschool_production

# Direct and Pooled Connection URLs
DATABASE_URL="postgresql://yene_admin:YOUR_STRONG_RANDOM_PASSWORD_HERE@postgres:5432/yeneschool_production?schema=public"
DATABASE_POOL_URL="postgresql://yene_admin:YOUR_STRONG_RANDOM_PASSWORD_HERE@pgbouncer:6432/yeneschool_production?schema=public"

# Security & Authentication
JWT_SECRET=GENERATE_64_CHAR_RANDOM_HEX_STRING
JWT_EXPIRES_IN=15m
REFRESH_TOKEN_SECRET=GENERATE_ANOTHER_64_CHAR_RANDOM_HEX_STRING
REFRESH_TOKEN_EXPIRES_IN=7d

# Cache & Queues
REDIS_URL=redis://redis:6379

# AI Assistant Providers (OpenRouter / Gemini)
AI_PROVIDER=gemini
AI_MODEL=models/gemini-2.5-flash
AI_API_KEY=your_gemini_api_key_here

# Base URL for Email & Push Callbacks
APP_BASE_URL=https://yeneschool.me

3. Launching the Production Stack

Build and start all services in detached mode:

docker compose up -d --build

Verify that all service containers are healthy:

docker compose ps

Expected healthy output:

NAME           IMAGE                      STATUS                   PORTS
sms_postgres   pgvector/pgvector:pg16     Up (healthy)             0.0.0.0:5433->5432/tcp
sms_redis      redis:7-alpine             Up (healthy)             6379/tcp
sms_pgbouncer  edoburu/pgbouncer          Up (healthy)             6432/tcp
sms_backend    yeneschool/backend         Up (healthy)             8001/tcp
sms_frontend   yeneschool/frontend        Up (healthy)             3000/tcp
sms_nginx      nginx:alpine               Up (healthy)             0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp

4. Applying Database Migrations

Once the database container is healthy, run Prisma migrations to build the relational schema:

# Execute migrations inside the running backend container
docker compose exec backend npx prisma migrate deploy

# (Optional) Seed initial system permissions and superadmin user
docker compose exec backend npx prisma db seed

5. Monitoring Logs & Operational Verification

Stream logs from specific services to verify normal operation:

# Stream backend API logs
docker compose logs -f backend

# Stream background queue worker logs
docker compose logs -f redis

# Stream Nginx access and error logs
docker compose logs -f nginx

To gracefully stop or restart the stack:

# Restart stack with zero data loss (volumes remain persistent)
docker compose restart

# Shutdown stack
docker compose down