Installing from source

If you already run Node applications and manage your own PostgreSQL, this is the least surprising way to install Plugboard. One launcher script handles setup, migrations and starting every service.

Requirements

Node.js 20.9 or later
pnpm (npm i -g pnpm, or corepack enable)
PostgreSQL 14 or later, reachable by connection string

Redis is optional and only used by the legacy people-sync and daily-digest worker. SLA checks, backups, reports and monitors all run in-process.

Install

pnpm install
node scripts/plugboard.mjs setup

setup writes a .env containing strong random values for JWT_SECRET, SECRETS_MASTER_KEY and the rest. Open it and point the database at your server:

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

Then start it:

node scripts/plugboard.mjs start

The launcher builds on the first run, applies pending migrations with prisma migrate deploy, and starts the API and the web process in one foreground process. Ctrl+C stops everything.

Open http://localhost:3000.

Shortcuts

Same thing, less typing:

Windows: Plugboard.cmd setup once, then double-click Plugboard.cmd.
macOS and Linux: ./plugboard.sh setup once, then ./plugboard.sh.
Either: pnpm setup then pnpm start.

Commands

plugboard below means node scripts/plugboard.mjs.

Command	What it does
`plugboard setup`	Create `.env` with generated `JWT_SECRET`, `SECRETS_MASTER_KEY` and other secrets
`plugboard migrate`	Apply pending database migrations
`plugboard seed`	Load the fictional demo data. Optional, for evaluation
`plugboard start`	Migrate, then start the API and web

Flags on `start`

Flag	Effect
`--skip-migrate`	Do not run migrations. Useful when a DBA applies them separately
`--no-build`	Skip the build. Use in production where the build already happened
`--worker`	Also start the Redis-backed worker

A production service definition normally uses start --no-build, so a restart is fast and cannot fail on a compilation error.

Development stack

If you want PostgreSQL, Redis and MinIO without installing them:

corepack enable && corepack prepare [email protected] --activate
pnpm install
cp .env.example .env
pnpm infra:up          # Postgres + Redis + MinIO, needs Docker
pnpm db:migrate && pnpm db:seed
pnpm dev               # api :4000 · web :3000 · worker

pnpm dev runs everything with hot reload. This is the development setup, not a production one.

Keeping it running

Run it under a process manager so it restarts on boot and after a crash.

systemd:

[Unit]
Description=Plugboard
After=network.target postgresql.service

[Service]
WorkingDirectory=/opt/plugboard
ExecStart=/usr/bin/node scripts/plugboard.mjs start --no-build
EnvironmentFile=/opt/plugboard/.env
Restart=always
RestartSec=5
User=plugboard

[Install]
WantedBy=multi-user.target

Windows: run Plugboard.cmd from Task Scheduler at system startup, or wrap it with NSSM. The service install page explains why a plain Node process cannot be a Windows Service and what to do about it.

pm2:

pm2 start scripts/plugboard.mjs --name plugboard -- start --no-build
pm2 save
pm2 startup

Updating a source install

git fetch --tags
git checkout v0.2.0
pnpm install
node scripts/plugboard.mjs migrate

Then restart the service. Read the changelog first: releases marked with a migration warning change the schema and deserve a quiet window and a fresh backup.

Take a database dump before migrating. Migrations are forward-only, so there is no automatic way back.

HTTPS

The launcher serves plain HTTP on localhost. For anything a staff member reaches, terminate TLS at a reverse proxy or point the API at a certificate directly. See HTTPS and certificates.

Set both origins to the address people actually type:

API_URL="https://helpdesk.yourschool.org"
WEB_URL="https://helpdesk.yourschool.org"

WEB_URL is used in emailed tracking links, so it has to be the real one.

Backups and the master key

SECRETS_MASTER_KEY encrypts connector credentials and backups. Store a copy somewhere separate from the server.

The application takes its own encrypted, scheduled backups from Admin, Backups. Getting them off the machine is yours. See backups and restore.