Command line

Three command line surfaces: the launcher for source installs, the on-premises binary for the portable bundle, and the update script for Docker deployments.

The launcher

For a source install. plugboard below means node scripts/plugboard.mjs.

Command	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
`plugboard start`	Migrate, then start the API and web

Flags on `start`

Flag	Effect
`--skip-migrate`	Do not run migrations
`--no-build`	Skip the build. Use in production, where it 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.

Shortcuts

Platform
Windows	`Plugboard.cmd`
macOS and Linux	`./plugboard.sh`
Either	`pnpm setup`, `pnpm start`

Development

Command	Does
`pnpm install`	Install dependencies
`pnpm infra:up`	PostgreSQL, Redis and MinIO via Docker
`pnpm db:migrate`	Apply migrations
`pnpm db:seed`	Load demo data
`pnpm dev`	API on 4000, web on 3000, worker, all with hot reload

The on-premises binary

For the portable bundle. ./plugboard on macOS and Linux, plugboard.cmd on Windows.

Command	Does
`plugboard install-service`	Register with the platform so it starts at boot
`plugboard uninstall-service`	Remove the registration. Data is left alone
`plugboard service-status`	Ask the platform how it is doing
`plugboard update --check`	Is there a newer release? Change nothing
`plugboard update`	Download and stage it now

Starting it

Platform
Windows	Double-click `Start-Plugboard.cmd`
macOS and Linux	`./start-plugboard.sh`

Service install flags

Flag	Effect
`--user someone`	The account the Linux service runs as

Requires elevation: sudo on Linux and macOS, an elevated shell on Windows.

The update script

For Docker deployments. Also what we run on managed hosting.

./scripts/plugboard-update.sh 0.2.0

Form	Does
`plugboard-update.sh <version>`	Update to that version, or roll back to it
`plugboard-update.sh <sha256:digest>`	Update to a pinned digest
`plugboard-update.sh <version> --dry-run`	Check the stack and pull the image, changing nothing

The script prints the rollback command at the end of every successful run, so the way back is always in your scrollback.

See updating.

Docker Compose

# Start
docker compose --env-file .env -f docker-compose.prod.yml up -d

# With an ingress profile
docker compose --env-file .env -f docker-compose.prod.yml --profile caddy up -d
docker compose --env-file .env -f docker-compose.prod.yml --profile tunnel up -d

# What is running
docker compose -f docker-compose.prod.yml ps

# Logs
docker compose -f docker-compose.prod.yml logs -f api

# A database shell
docker compose -f docker-compose.prod.yml exec postgres psql -U plugboard

# A manual dump
docker compose -f docker-compose.prod.yml exec postgres \
  pg_dump -U plugboard -Fc plugboard > backups/manual.dump

# Stop, keeping data
docker compose -f docker-compose.prod.yml down

# Stop and delete the database volume. Destructive
docker compose -f docker-compose.prod.yml down -v

Building the bundle

pnpm install
node scripts/package-bundle.mjs                        # uses your Node
node scripts/package-bundle.mjs --with-node --archive  # embeds Node, makes an archive

The release workflow runs exactly this per operating system on every v* tag.

Verifying a release

# Portable bundles, against the checksum beside the download
sha256sum -c plugboard-linux-x64.tar.gz.sha256

# Container images
cosign verify ghcr.io/samiossoftware/plugboard@sha256:1a2b3c... \
  --certificate-identity-regexp '^https://github.com/samiossoftware/plugboard/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

cosign download attestation ghcr.io/samiossoftware/plugboard@sha256:1a2b3c...

Health checks

curl -s https://helpdesk.yourschool.org/api/health/version
curl -s https://helpdesk.yourschool.org/api/health/ready

Both answer without a tenant and without a database, so they still work when nothing else does.