Quick start

Three routes to a running system. Pick by what you already have installed.

Fastest: the portable bundle

Nothing to install. The archive carries its own PostgreSQL, and optionally its own Node runtime.

Sign in to the download centre with the administrator email address on your deployment, and take the archive for your machine:

Machine	File
Windows	`plugboard-win32-x64.zip`
Linux, Intel or AMD	`plugboard-linux-x64.tar.gz`
Linux, ARM	`plugboard-linux-arm64.tar.gz`
macOS, Apple silicon	`plugboard-darwin-arm64.tar.gz`
macOS, Intel	`plugboard-darwin-x64.tar.gz`

Check it against the checksum published beside it before unpacking:
Terminal window
```
sha256sum -c plugboard-linux-x64.tar.gz.sha256
```
Unpack it somewhere permanent. The database lives inside the folder, so do not use Downloads or a temp directory.
Start it. Windows: double-click Start-Plugboard.cmd. macOS or Linux:
Terminal window
```
./start-plugboard.sh
```

First run creates the database in ./.pgdata, applies migrations, loads starter data and opens http://localhost:3000.

Full detail, including how to build the bundle yourself, is in the portable bundle.

If you have Node and PostgreSQL

You need Node 20.9 or later, pnpm, and a PostgreSQL 14 or later you can point a connection string at.

pnpm install
node scripts/plugboard.mjs setup

setup writes a .env with freshly generated secrets. Open it and point DATABASE_URL at your database:

DATABASE_URL="postgresql://user:pass@localhost:5432/plugboard?schema=public"

Then:

node scripts/plugboard.mjs start

That builds on first run, applies migrations, and starts the API and the web app in one foreground process. Ctrl+C stops everything.

Shortcuts exist: Plugboard.cmd on Windows, ./plugboard.sh on macOS and Linux, or pnpm setup and pnpm start.

Load the fictional sample data if you want something to look at:

node scripts/plugboard.mjs seed

See installing from source for the full set of flags and what each command does.

If you would rather use Docker

The development stack brings up PostgreSQL, Redis and MinIO, and you run the app from source against them:

corepack enable && corepack prepare pnpm@9.12.0 --activate
pnpm install
cp .env.example .env
pnpm infra:up
pnpm db:migrate && pnpm db:seed
pnpm dev

That gives you the API on port 4000, the web app on 3000 and the worker running.

For a production Docker deployment, which pulls a published image rather than building from source, see Docker Compose.

What to do first

Once you are signed in:

Open Admin, Features and look at the module list. Turn off what you will never use. See modules.
Open Admin, Connectors and switch on a connector in demo mode. Every feature that depends on it will now do something, using fictional data. This is the fastest way to see what the product does without hunting for credentials.
Open a submission from the sample data and work it through to closed, so you have seen the lifecycle.
Open /portal in another tab to see what a student sees.

Then go to the setup checklist when you are ready to put real data in.

The sample data

A fresh install seeds fictional students, staff, devices, loans and repairs. Nothing in it is based on a real person. It exists so every screen has something on it on the first visit.

To start with an empty system instead, do not run seed. A fresh on-premises install starts empty; set PLUGBOARD_DEMO_DATA=1 before the first start if you want the sample data. Once a database has real records in it, the seeder will not touch it.