Getting Started

One codebase, three apps — server (apps/server), worker (apps/worker), audit (apps/audit). The thing to get straight before anything else is what runs where, because only half the stack is on your machine.

What runs where

Step 1: Toolchain

corepack enable
corepack prepare pnpm@latest --activate
brew install go-task    # or see taskfile.dev/installation

Every task is a thin alias over a pnpm script, so pnpm <script> always works too. Run task with no arguments to list everything.

Step 2: Install

task setup

That runs pnpm install and scaffolds an empty .env.local (it will never clobber an existing one). One install at the root covers all three apps and installs Husky git hooks.

Chowbea installs with it. chowbea-axios is a normal dependency in package.json, so there is no separate or global install on the API side — after task setup the chowbea-axios binary and its busHandler() are both available. (The Education Hub is the repo that historically used a global CLI.)

Step 3: Fill in .env.local

There is no .env.example. task setup leaves you a file with three comment lines; everything else you fill in.

Config is validated by a Zod schema (libs/shared/src/config/env.config.ts) at boot, and a missing key stops the process with Config validation error: … naming it.

The four you can set yourself, because they point at your own machine:

PORT=8000
HOST=0.0.0.0
NODE_ENV=development
FRONTEND_URL=http://localhost:3000   # comma-separated for multiple CORS origins

REDIS_URL=redis://localhost:6379     # matches task infra
CENTRIFUGO_URL=http://localhost:8006 # matches task infra

REDIS_URL and CENTRIFUGO_URL already default to exactly these values, so you can omit them. DATABASE_URL (Neon) and RABBIT_MQ_URL (CloudAMQP) are shared credentials — never invent them, and never commit the file. Full inventory: Config & Environment.

Step 4: Start local infra

task infra          # Redis + Centrifugo, detached
task infra:status   # are they up?
task infra:logs     # tail both
task infra:down     # stop and remove

This is the fast loop: containers for the two things you don't want to install, everything else on your host where the debugger and file watcher work properly.

Centrifugo reads centrifugo.config.json from the repo root, which hardcodes the dev HMAC secret and API key that CENTRIFUGO_HMAC_SECRET / CENTRIFUGO_API_KEY default to — so they line up with no configuration. Its admin UI is at http://localhost:8006 (password admin).

Step 5: Run migrations

task migration:run

Schema is TypeORM migrations under database/migrations/, applied by hand — never auto-generated and never applied on boot.

Step 6: Run the apps

task dev            # server + worker + audit together, watch mode

Colour-coded output: api blue, worker green, audit yellow. One at a time while iterating:

task dev:server     # apps/server — the HTTP API
task dev:worker     # apps/worker — jobs, and the Rover agent graph
task dev:audit      # apps/audit  — audit-log consumer
task email          # React Email preview server

Step 7: The type bus

The Education Hub generates its types from this repo. Two pipes — OpenAPI for REST, the type bus for everything Swagger cannot carry. Full picture: How Chowbea works.

task bus            # extract → chowbea.bus.json
task bus:watch      # re-extract on save — run this while working on shared types
task bus:check      # validate without writing (the CI gate)
task bus:diff       # compare against staging, fail on removed types

The server serves the manifest at /.well-known/chowbea.json, re-reading the file when it changes — so task bus:watch plus a running server gives the Hub live types with no restart. prebuild runs extract automatically, so a build never ships a stale manifest.

Step 8: Check it works

Everything mounts under the global prefix api/v1.

Open Scalar and fire a request. A response means the apps, Neon, Redis, and RabbitMQ are all wired up.

/docs* is open in development; elsewhere it sits behind HTTP Basic Auth (DOCS_USERNAME / DOCS_PASSWORD).

Logging in

• Seeding — in development, SchoolSeedService ensures a fixed demo school exists (the tenant users attach to). Skipped outside development.
• Login — every address in SUPERADMIN_EMAILS is provisioned as a passwordless platform admin. Sign in by requesting an emailed one-time code.
• Demo data — pnpm seed:stress stamps extra data onto the demo school. Not needed on day one.

SUPERADMIN_EMAILS grants platform admin, above any school. For a school-scoped super admin, add your email to that school's SchoolConfig.superAdminEmails. See Auth & Permissions.

Everything in Docker

The alternative mode builds and runs the three apps as containers too, with ./apps and ./libs bind-mounted so watch mode still works:

task docker:dev         # foreground, builds on first run
task docker:dev:down

Slower to start and awkward to attach a debugger to. Use it to reproduce a container-only problem, not for daily work.

Taskfile reference

Where to go next