The portable bundle

The bundle is Plugboard packaged with everything it needs: the built application, a PostgreSQL server, and optionally a Node runtime. Unzip it and start it. There is nothing to install, nothing to configure before the first run, and nothing left behind on the machine when you delete the folder.

It exists for two reasons. Evaluating a product should not require provisioning a database, and a lot of small schools want one folder they can back up.

Download and verify

Archives come from the download centre. Sign in with the administrator email address on your deployment; there is no account and no password.

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

Every archive has a checksum published beside it. Check before you unpack:

sha256sum -c plugboard-linux-x64.tar.gz.sha256

On Windows PowerShell:

Get-FileHash .\plugboard-win32-x64.zip -Algorithm SHA256

and compare it against the matching .sha256 file. This matters more than the usual hand-waving about checksums, because the automatic updater runs unattended with privileges and refuses any archive whose hash does not match. Doing the same by hand on the first download keeps the chain intact from the start.

Unpack it somewhere permanent

The database lives inside the folder. Do not unpack into Downloads, a temp directory, a roaming profile, or anywhere your endpoint management cleans up.

Good choices:

• C:\Plugboard on Windows
• /opt/plugboard on Linux
• /Applications/Plugboard or /opt/plugboard on macOS

Start it

Windows: double-click Start-Plugboard.cmd.

macOS and Linux:

./start-plugboard.sh

On the first run it:

1. writes a .env with freshly generated secrets,
2. creates a PostgreSQL cluster in ./.pgdata,
3. applies every migration,
4. starts the API and the web process,
5. opens http://localhost:3000.

A fresh on-premises install starts with an empty database and no demo data. You create the first administrator, and the system is yours from the first sign-in.

To get the fictional sample data instead, for a demonstration or a training environment, set PLUGBOARD_DEMO_DATA=1 before the first start. It only ever applies to a brand new database and will never touch one with real records in it.

What lives where

Everything is inside the install directory, so backing up the folder backs up the instance.

.env                 your configuration and secrets
.pgdata/             the database
backups/             pre-update database dumps
logs/                service output on Windows and macOS; Linux uses journald
.previous-version/   the bundle you were on before the last update

Moving the instance to another machine is a matter of stopping it, copying the folder, and starting it there.

Configure it

Open .env and set the address people will actually type:

PUBLIC_URL=https://helpdesk.yourschool.org
PUBLIC_HOST=helpdesk.yourschool.org

PUBLIC_URL is not cosmetic. It is the CORS allow-list, the base for every link the product emails, the SSO redirect target and the portal address. Set it to an internal name and you will generate links your users cannot open.

Then point it at your certificate. See HTTPS and certificates.

The full list of settings is in environment variables.

Back up the master key

SECRETS_MASTER_KEY in .env encrypts your connector credentials and your backups. Copy it into a password manager now, before you have anything worth losing.

A database backup restored without that key cannot decrypt its own secrets. That is the difference between a recoverable outage and permanent data loss, and it is the one thing only you can do.

Make it survive a reboot

The bundle in the foreground is fine for a look. For anything real, register it as a service so it comes back after a reboot with nobody logged in:

sudo ./plugboard install-service

See running it as a service, which covers the Windows caveat honestly.

Keeping it current

The bundle checks for a newer release every night at 01:00 in the machine’s own local time, downloads it, verifies it against its published checksum, and stages it. The swap happens on restart, because replacing files a running process holds open is how updaters corrupt themselves, particularly on Windows.

./plugboard update --check     # is there one? change nothing
./plugboard update             # get it now

See updating for the settings and for rolling back.

Building the bundle yourself

From a source checkout:

pnpm install
node scripts/package-bundle.mjs

That produces release/plugboard/ using the Node runtime already on your machine. To embed a Node runtime and produce a distributable archive:

node scripts/package-bundle.mjs --with-node --archive

The release pipeline runs exactly this per operating system on every tagged version, and the results are what gets copied into the download centre. A bundle you build yourself is the same artefact.

Limits worth knowing

• One copy at a time. The bundle runs a single application process. A second copy would not know what the first was doing, so live updates would miss changes. Scale up rather than out.
• No TLS on the web tier without a proxy. The API can serve HTTPS itself, but the web process cannot. For full HTTPS put a reverse proxy in front, which is the recommended setup anyway.
• The embedded PostgreSQL is a real PostgreSQL, but it is tuned for a single machine. A site above five thousand devices should consider a separate database host and a source or Docker install.