# Deploying to Netlify (with a free managed database)

This app needs a real Postgres database — see the note in the main
README/TESTING.md about why a "no database" version isn't viable for
an actual school running exams. The good news: you don't need to run
or manage that database yourself. A free managed Postgres pairs with
Netlify in about 5 minutes and costs nothing at a single school's
scale.

## 1. Create a free Postgres database (Neon)

1. Go to **[neon.tech](https://neon.tech)** and sign up (free tier).
2. Create a new project.
3. On the project dashboard, copy the **pooled connection string**
   (Neon shows both a direct and a pooled one — use the **pooled**
   one for `DATABASE_URL`, since Netlify's serverless functions can
   open many concurrent connections and a connection pooler prevents
   that from exhausting Postgres's connection limit). It looks like:
   ```
   postgresql://user:password@ep-xxxx-pooler.region.aws.neon.tech/dbname?sslmode=require
   ```

*(Supabase or Railway's free Postgres tiers work the same way if you
prefer either of those instead — the steps below are identical, just
swap in their connection string.)*

## 2. Set up the schema on that database

From your local machine, with this project's dependencies installed:

```bash
export DATABASE_URL="<paste the Neon pooled connection string>"
npx prisma migrate deploy
npm run prisma:seed   # optional — creates a demo super admin + demo school
```

If you don't want the demo data on a real production database, skip
the seed step and instead create your first real school directly:
see "Creating your school's real account" below.

## 3. Push this project to GitHub

Netlify deploys from a Git repository, not a raw file upload.

```bash
cd cbt-platform
git init
git add .
git commit -m "Initial commit"
```

Create a new (private, recommended) repository on GitHub, then:

```bash
git remote add origin <your-repo-url>
git push -u origin main
```

## 4. Connect the repo to Netlify

1. In Netlify: **Add new site → Import an existing project → GitHub**
   → select your repo.
2. Netlify should auto-detect Next.js and read `netlify.toml` (already
   included in this project) — build command
   `npx prisma generate && npm run build`, publish directory `.next`.
3. **Before the first deploy, add environment variables** (Site
   settings → Environment variables):

   | Variable | Value |
   |---|---|
   | `DATABASE_URL` | the Neon pooled connection string from step 1 |
   | `NEXTAUTH_URL` | your Netlify site URL, e.g. `https://your-school.netlify.app` |
   | `NEXTAUTH_SECRET` | generate one: `openssl rand -base64 32` |

   Everything else in `.env.example` (AI, payments, S3) is **optional
   at launch** — every feature that needs them fails gracefully with a
   clear error only when that specific feature is used, so the school
   can go live on core CBT/results/report-cards today and add AI
   question generation, Paystack billing, or S3 photo storage later
   without redeploying from scratch.

4. Deploy.

## 5. Creating your school's real account

However you seeded the database (step 2's demo seed, or your own
script), you need at least one `SUPER_ADMIN` and one school with a
`SCHOOL_ADMIN` to actually start using it:

- If you ran `npm run prisma:seed`: log in as
  `admin@greenwood.local` / `ChangeMe123!` (school code
  `greenwood-college`) and **change that password immediately** — then
  either repurpose that seeded school or have the super admin
  (`superadmin@platform.local` / `ChangeMe123!`, also change this)
  create the real one via `POST /api/schools`.
- To create the real school directly instead of using the demo data,
  call `POST /api/schools` as the seeded super admin with the real
  school's name/slug/admin email — see `01-architecture.md` §3 or the
  request shape in `src/server/modules/schools/validation.ts`.

## 6. Known limits of this specific deployment path

- **Netlify functions have a request timeout** (10s on the free tier,
  26s on paid plans as of writing — check Netlify's current limits).
  AI question generation and PDF rendering are the two operations
  most likely to run long; if you hit timeouts on those specifically,
  that's the cause, not a bug in the code itself.
- **The Docker/docker-compose path in the main README is a separate,
  independent deployment option** — you don't need Docker at all for
  Netlify; the two are alternatives, not steps in the same process.
- Re-read `TESTING.md` before telling the school "we're live" — it
  walks through actually verifying the exam → grading → report-card
  pipeline works against your real database, which matters more than
  it might seem given none of this has been run in the environment it
  was written in.