Documentation — For developers

Installation & Deployment Guide

Deploy one instance of Schoolum — once live, it hosts unlimited schools under your own brand.

Prerequisites

Node.js 20+ and npm
A PostgreSQL database (Neon, Supabase, RDS, or any Postgres 14+ instance)
A hosting target for a Next.js app (Vercel is used in this guide; any Node.js host works)

1. Install dependencies

bash

git clone <your-repo-url>
cd schoolum
npm install

2. Provision the database

Create a Postgres database and note two connection strings:

A pooled connection (for the running app)
A direct connection (for running migrations — required for Vercel-style serverless deployments)

Set these as DATABASE_URL and DIRECT_URL. See the Environment Variables Reference for the full list.

3. Set required environment variables

At minimum:

DATABASE_URL=
DIRECT_URL=
AUTH_SECRET=       # generate with: openssl rand -base64 32
APP_URL=           # your deployed URL, e.g. https://app.yourschool.com

Everything else (payments, AI, live classes, file storage) is optional — each feature degrades gracefully with a clear “not configured” message instead of failing, so you can launch core features first and connect the rest later.

4. Run database migrations

bash

npx prisma migrate deploy

This applies the full schema (schools, users, students, academics, attendance, results, CBT, finance, communications, and the partner/buyer programs) in one pass.

5. (Optional) Seed demo data

bash

npx tsx prisma/seed/index.ts

Creates one demo school with sample students, staff, and records — useful for a sales demo or your own QA, not required for production.

6. Deploy

Push to your hosting provider (e.g. Vercel). Set the environment variables from step 3 in your hosting provider’s dashboard.

bash

npm run build
npm start

7. Create the first Super Admin and onboard a school

The Super Admin role sits above individual schools — it manages the plan catalog, platform billing, and every school on the instance.

Create the first Super Admin account directly in the database, or use the seed script above for a demo account (see the Architecture & Codebase Overview doc’s Role & permission system section).
Sign in and create your first school from the Super Admin area.
Invite that school's owner — they complete onboarding (school profile, academic structure, branding) from there.

Verifying the install

You can sign in as Super Admin
A school can be created and its owner can sign in
A student can be enrolled and a guardian invited to the parent portal
(If configured) a test email/SMS notification is delivered

Optional integrations

Feature	Requires
Branded email delivery	A Resend account (per-school or platform-wide fallback)
SMS notifications	A Twilio or Sent.dm account (per school)
AI assistant & CBT AI features	An OpenAI or Anthropic API key
Live virtual classrooms	A LiveKit Cloud or self-hosted LiveKit server
Lecture/file uploads	A Vercel Blob token
Live class recording	An S3-compatible bucket (works alongside LiveKit)
School payment collection	Each school connects its own Paystack/Flutterwave/Korapay account
Platform billing (charging schools)	Your own Paystack merchant account

Full variable names and behavior: see the Environment Variables Reference.