How it fits together
You can run Plugboard without reading this. It is here because a lot of the configuration makes more sense once you know what talks to what, and because it answers “why is this screen empty” more often than any troubleshooting page.
What actually runs
Section titled “What actually runs”A small deployment is two programs and a database. That is the whole thing.
| What it is | Default port | |
|---|---|---|
| The API | Everything behind the scenes: permissions, the connectors, the scheduled work | 4000 |
| The web app | The pages people look at | 3000 |
| PostgreSQL | Where everything is stored | 5432, never exposed |
Scheduled work happens inside the API on timers: service level checks, service monitors, backups, scheduled reports. There is no separate scheduler to install or babysit.
Two things are optional and most schools never need them:
- Redis, used only by a legacy roster sync and the daily digest.
- Object storage, only if you upload logos, photos or export files.
If you use the portable bundle, the database comes with it and there is nothing to install at all.
How a request finds your school
Section titled “How a request finds your school”Plugboard is built to serve many institutions, and a self-hosted install is simply one of them. The same code runs either way, so there is no separate single-school mode with its own quirks.
A request is matched to your institution by its web address. If you are on
helpdesk.yourschool.org, that hostname is recorded against your institution
and every request to it lands in your data.
The practical consequences:
- Changing your address is a real change, not a cosmetic one. See your own domain.
Unknown tenantas an error means the address does not match what is recorded. It is a one-line fix.- Health checks skip all of this, so monitoring keeps answering when nothing else does.
Your data cannot be seen by anyone else
Section titled “Your data cannot be seen by anyone else”Every record belongs to your institution, and that is enforced in the database itself rather than only in the application. A query that somehow forgot to ask for your institution returns nothing rather than everything.
On managed hosting there is a further separation: your own database, not a shared one. See tenant isolation for the version to put in front of a procurement officer.
Connectors, in one paragraph
Section titled “Connectors, in one paragraph”The application never depends on Jamf, or Synergetic, or Zendesk. It depends on a job to be done, such as “look up a device by serial number”, and a connector says which of those jobs it can do.
That is why a school running Intune and one running Jamf use the same repairs screen, and why swapping your MDM is a settings change rather than a project. When a feature needs something done, Plugboard finds an enabled connector that can do it. If there is not one, the feature says so plainly instead of failing in a confusing way.
Your credentials are encrypted before they are stored and are only unlocked in memory for the moment a call is made. A connector never gets to touch the database.
The systems that need something extra
Section titled “The systems that need something extra”Most connectors reach a supplier over the internet and work the same wherever Plugboard is running.
A few reach systems that live inside your school network: Active Directory, a Synergetic database, PaperCut, Web Help Desk, printers answering on the LAN.
- If you host Plugboard yourself on that network, it reaches them directly and there is nothing extra to do.
- If we host it, install a connector agent: a small program inside your network that dials out and does the work locally. There is no firewall rule to request, which is usually the difference between a two week change request and an afternoon.
Each connector’s page says which of these it is.
The desk updates itself
Section titled “The desk updates itself”When a colleague changes something, your screen follows without a reload, so two technicians do not both pick up the same job. See live updates.