Skip to content
plugboard.appRequest a demo

Install it yourself

Your own domain

Plugboard normally runs on your own domain, such as helpdesk.yourschool.org. Staff trust a link on a domain they recognise, and a service desk sends a lot of links.

Plugboard first picks one tenant slug to try, from the first of these that applies:

  1. An explicit x-tenant-slug header, used by API clients and local development.
  2. The first label of the hostname (scots in scots.plugboard.app), unless it is www or localhost, or the host is an IPv4 address or has no dot.
  3. DEFAULT_TENANT_SLUG, for a single-tenant self-hosted install.

It then makes one lookup for an active tenant whose slug is that one or whose primaryDomain is the Host header. The two are tried together rather than in sequence, because a custom domain usually has no meaningful first label. “helpdesk” in helpdesk.yourschool.org is a hostname label, not a tenant name, and the primaryDomain match is what makes a custom domain work.

Health and metrics endpoints skip all of this, so probes keep working when nothing else does.

helpdesk.yourschool.org. A 203.0.113.10
helpdesk.yourschool.org. AAAA 2001:db8::10

In .env, both must be the address people type:

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

On a source install the equivalent pair is:

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

PUBLIC_URL is the CORS allow-list, the base for every emailed link, the SSO redirect target and the portal address. Setting it to an internal name produces links your users cannot open.

Covered in full in HTTPS and certificates. The short version:

SituationApproach
Publicly reachable, ports 80 and 443 openCaddy with automatic Let’s Encrypt
School network you do not controlCloudflare Tunnel, no inbound ports
You already own a wildcardPoint Caddy or nginx at it
Internal CA or AD Certificate ServicesPEM or PKCS#12 straight on the application
You already run a reverse proxyStart the stack with no ingress profile and proxy to it

If the desk should not be reachable from outside the school, use split-horizon DNS: the name resolves to a private address inside and to nothing outside. Use an internal CA or a DNS-01 Let’s Encrypt challenge, since HTTP-01 needs public reachability.

Remember ALLOW_PRIVATE_EGRESS=1 if you also want service monitors to check addresses on your LAN. Plugboard blocks outbound requests to private ranges by default so a tenant-supplied URL cannot be used to reach internal hosts.

Supported, and there are three things to update together. Miss one and the symptom appears somewhere unrelated.

The configuration. PUBLIC_URL and PUBLIC_HOST, then restart.

Your identity provider. SSO redirect URIs are absolute. Add the new one before switching, keep both registered during the change, then remove the old one afterwards. Skipping this locks everyone out of SSO at cutover.

Links already sent. Keep the old hostname resolving and redirecting for a while. Tickets contain tracking links people return to months later.

yourschool.org with no subdomain needs a CNAME-flattening or ALIAS record, which not every DNS provider offers. A subdomain is simpler, and schools almost always want one anyway.

SymptomCause
Unknown tenant: helpdeskprimaryDomain is not set for your tenant, or does not match the Host header. It is compared lower-cased and without the port
CORS errors in the browser consolePUBLIC_URL does not match the address bar. Scheme and trailing slash both count
Emails link to the wrong hostPUBLIC_URL still points at the old origin, or the process was not restarted
SSO fails right after a domain changeThe redirect URI at the identity provider is still the old one
Realtime updates arrive in burstsA proxy is buffering /api/events/*
Certificate never issuesPort 80 unreachable, so the HTTP-01 challenge fails