Skip to main content
Version: Next

Deploy with the Backend School Bundle

This is the standard production workflow for deploying both the backend and frontend to a school site.

What the bundle deploys​

The backend school bundle runs the full school stack:

  • frontend
  • backend
  • PostgreSQL
  • Redis
  • MinIO
  • migration container
  • notification worker
  • nginx reverse proxy

Support should preferably give the school an already assembled release directory and, when needed, the matching archive plus checksum for transfer verification.

The working directory typically looks like this:

school-bundle-release-<releaseVersion>/
  school-bundle/
  docs/
  scripts/
  RELEASE-BUNDLE.json

Step 1: Verify transfer if an archive was provided​

If support provided the tarball and checksum manifest, verify and extract it first.

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File .\scripts\extract-school-bundle-release.ps1 `
  -Archive .\school-bundle-release-<releaseVersion>.tar.gz `
  -ChecksumFile .\school-bundle-release-<releaseVersion>.tar.gz.sha256.json `
  -OutputDir .

If the release is signed, place trusted-release-signing-public.pem beside the bundle before install.

Step 2: Enter the bundle directory​

cd .\school-bundle-release-<releaseVersion>\school-bundle

Step 3: Prepare configuration​

Create the school configuration file if it does not already exist:

copy .env.school.example .env.school

Fill in the school-specific values support provided.

Copy These From The Cloud Handoff Form

Before install, support should hand the operator a deployment handoff containing these exact values:

  • TENANT_ID
  • LOCAL_SCHOOL_ID
  • any school-specific licensing values

The operator should generate or confirm SITE_ID for the physical appliance once, write it into .env.school, and keep it unchanged for the lifetime of that installation.

Typical values to confirm:

  • tenant or site-specific licensing values
  • image overrides when support uses a local registry mirror
  • deployment secrets or credentials that must not remain placeholders

Required identity values in .env.school:

  • TENANT_ID: the tenant UUID assigned to the school's owning tenant
  • LOCAL_SCHOOL_ID: the UUID of the school record this appliance is being deployed for
  • SITE_ID: a stable identifier for this physical server or appliance

Where they come from:

  1. TENANT_ID comes from the cloud-side provisioning or onboarding handoff.
  2. LOCAL_SCHOOL_ID comes from the cloud-side school record created for that school.
  3. SITE_ID is created for the appliance during first install and then kept unchanged for the lifetime of that installation.

Operator rules:

  • Do not invent or regenerate TENANT_ID or LOCAL_SCHOOL_ID locally. They are issued values.
  • Generate SITE_ID once and keep it stable across updates, restores, and reboots.
  • On a fresh install, set TENANT_ID explicitly in .env.school. Do not rely on the local database to infer it before bootstrap has completed.

Example:

TENANT_ID=872880db-b6e6-4ebc-a3e3-078f023cb041
LOCAL_SCHOOL_ID=5db0c8d4-c9f6-4f1a-b56d-8cb3d8dd6f2a
SITE_ID=school-laptop-eg2fltlv

Step 4: Run preflight​

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File .\preflight-check.ps1

Preflight must succeed before install or update.

Step 5: Install​

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File .\install.ps1

What happens during install:

  1. tool readiness is checked
  2. .env.school is validated
  3. bundle checksum and optional signature are verified
  4. pinned image tags are read from release-manifest.json
  5. images are pulled
  6. PostgreSQL, Redis, MinIO, and initialization services start
  7. backend migrations run from the released backend image
  8. backend, worker, frontend, and nginx start
  9. health checks run through the reverse proxy

After health checks pass, the bundle also runs the backend bootstrap sync CLI. In local or hybrid mode, it uses TENANT_ID, LOCAL_SCHOOL_ID, and SITE_ID to pull the school's cloud data into the local database before the deployment is treated as complete.

That bootstrap pull is scoped by these effective values:

x-tenant-id: <TENANT_ID>
x-school-id: <LOCAL_SCHOOL_ID>
x-site-id: <SITE_ID>

If deployment licensing is enabled, any tenant_id, school_id, and site_id claims in the signed license token must also match these configured values.

Step 6: Verify deployment​

Confirm these before handing the system to end users:

  • the frontend loads through the school URL or LAN address
  • backend health succeeds
  • migrations completed without error
  • the bundle install did not report checksum, signature, or license failures

Step 7: Update later releases​

Use the packaged update command, not raw compose commands:

powershell -ExecutionPolicy Bypass -File .\update.ps1

The update flow reuses the same verification and health-check model as install.

Step 8: Roll back only with support guidance​

If a release fails after update:

  • stop and collect logs
  • use the previously approved release directory
  • rerun the packaged update or reinstall path from that known-good bundle

Do not improvise by mixing files from different bundle versions.