Administration
Deployment
Frontline PSA is self-hosted. This page is for the administrator who installs it. It covers a local trial, a production installation, and the settings that connect the optional services.
What you need
| Component | Requirement |
|---|---|
| Runtime | Node.js 22.9 or later, or Docker |
| Database | PostgreSQL 16 or later. A local trial uses an embedded database (PGlite) instead and needs nothing installed. |
| Sign-in | Cloudflare Access in front of the app (production) |
| File storage | A persistent directory for attachments |
| Optional | An OpenAI-compatible AI gateway, a DPMem service, and DPGatekeeper for customer tenants |
Try it locally
A trial needs no configuration.
- Install the dependencies with
npm install. - Start the app with
npm run dev. - Open
http://localhost:5173.
On first start, Frontline PSA creates an embedded database in the data/pglite folder and fills it with a demo MSP: customers, tickets, contracts, time, invoices, projects, devices and knowledge base articles. You are signed in as the demo administrator.
In a trial, the AI model, customer memory, the Scout agent and DPGatekeeper are all stand-ins, and the screens that use them carry tags such as MOCK MODEL and MOCK GATEKEEPER. To start again with fresh demo data, run npm run db:reset.
Note: The embedded database is for trials. Use PostgreSQL for real work.
Install for production
With Node
- Create an empty PostgreSQL database.
- Copy
.env.exampleto.envand set at leastNODE_ENV=production,DATABASE_URL,CF_ACCESS_TEAM_DOMAINandCF_ACCESS_AUD. - Set
PSA_BOOTSTRAP_ADMIN_EMAILto your own email for the first start (see below). - Build the app with
npm run build. - Create the database tables with
npm run db:migrate. - Start the app with
npm start, from the folder that contains the app.
Run npm run db:migrate again each time you upgrade. Production does not apply database changes or load demo data by itself, unless you set PSA_AUTO_MIGRATE=1.
With Docker
The supplied Dockerfile builds a production image on Node 22. The container:
- Listens on port 8080.
- Stores attachments in
/data/attachments. Mount a volume there. - Answers a health check at
/healthzwithout sign-in. - Expects to sit behind a reverse proxy that sets the forwarded host and protocol headers.
Pass the same settings as environment variables. Run the migration step on each deploy, or set PSA_AUTO_MIGRATE=1 if you run a single instance.
The first administrator
An empty production database has no users, so nobody could sign in. When PSA_BOOTSTRAP_ADMIN_EMAIL is set and the database has no resources, the first start creates:
- The standard picklists, departments, roles, queues, work types and SLAs.
- Your own company, with business hours of 08:00 to 17:00 on weekdays.
- One administrator with that email.
It never adds demo customers or tickets, and it does nothing once any resource exists. Sign in as that administrator, then add everyone else under Admin → Resources. See Administration.
Sign-in
In production, Frontline PSA accepts sign-in only through Cloudflare Access.
- Without
CF_ACCESS_TEAM_DOMAINandCF_ACCESS_AUD, every request is refused. - Each person's Access email must match the email of an active resource exactly. Otherwise they see a "not an active Frontline PSA user" page.
- There are no local passwords, and the development sign-in is ignored in production.
Two paths are called by machines, not people, and must be allowed through Access with a bypass or service-token policy:
| Path | Used by |
|---|---|
/atservicesrest/* | Integrations using the Autotask-compatible API. They authenticate with their API user's credentials. |
/api/scout/v1/* | The Scout agent on a customer device. It authenticates with its one-time session token. |
Settings
All settings are environment variables. .env.example lists every one with a comment.
Core
| Variable | Purpose |
|---|---|
NODE_ENV | Set to production. A built server started without it is also treated as production. |
DATABASE_URL | PostgreSQL connection string. If unset, the embedded database is used. |
CF_ACCESS_TEAM_DOMAIN | Your Cloudflare Access team domain, for example yourteam.cloudflareaccess.com. |
CF_ACCESS_AUD | The AUD tag of the Access application. |
ATTACHMENTS_DIR | Where uploaded files are stored. Default ./data/attachments. |
BODY_SIZE_LIMIT | Largest request the server accepts. npm start and the Docker image set 26M so that 25 MB attachments fit. |
PSA_BOOTSTRAP_ADMIN_EMAIL | Email of the first administrator, used only on an empty database. |
PSA_BOOTSTRAP_ADMIN_NAME, PSA_COMPANY_NAME, PSA_TIMEZONE | Name of that administrator, your company name and your time zone for the first start. |
PSA_AUTO_MIGRATE | Set to 1 to apply database changes at startup. |
AI triage and Scout
| Variable | Purpose |
|---|---|
LITELLM_BASE_URL, LITELLM_API_KEY | Address and key of an OpenAI-compatible AI gateway. With a key set, AI runs live. |
AI_MODE | live, mock or off. In production the default is off until a key is set. |
AI_MODEL, AI_FAST_MODEL | Model names to request from the gateway. |
AI_MAX_TOKENS, AI_TIMEOUT_MS | Limits for each model call. |
SCOUT_DISPATCH | manual in production: the technician runs the launcher on the device. |
SCOUT_PUBLIC_URL | The address customer devices use to reach Frontline PSA. |
SCOUT_LEDGER_KEY | Secret used to sign the Scout ledger. Set it in production and keep it safe. |
SCOUT_AGENT_NO_SHOW_SECONDS | How long a session waits for the agent to connect. Default 900 in production. |
Customer memory (DPMem)
| Variable | Purpose |
|---|---|
PALACE_MODE | live, mock or off. In production the default is off until fully configured. |
PALACE_URL | Address of the DPMem service. |
PALACE_CERT_FILE, PALACE_KEY_FILE | Client certificate and key. Both are required, together with the API key. |
PALACE_API_KEY | API key for the DPMem service. |
PALACE_SHARED_NAMESPACE | Name of the memory shared across customers. Default shared. |
After connecting, a DPMem administrator must grant Frontline PSA write access to each customer's memory. Then map companies and sync the knowledge base on Intelligence → Memory. See Customer memory (DPMem).
Customer tenants (DPGatekeeper)
| Variable | Purpose |
|---|---|
GATEKEEPER_MODE | mock or live. Production always runs live. |
GATEKEEPER_URL | Address of your DPGatekeeper. It must be HTTPS and match Gatekeeper's own public address exactly. |
GATEKEEPER_ENTRA_TENANT_ID, GATEKEEPER_ENTRA_CLIENT_ID, GATEKEEPER_ENTRA_CLIENT_SECRET, GATEKEEPER_ENTRA_SCOPE | The Microsoft Entra application Frontline PSA uses to identify itself to Gatekeeper. Set all four. |
GATEKEEPER_TOKEN_FILE, GATEKEEPER_TOKEN | Alternatives to Entra: a token read from a file, or a fixed token. |
GATEKEEPER_CONSOLE_URL | Address of the Gatekeeper console, used for the links to where approvals happen. |
Frontline PSA stores no vendor credentials. Tenants, connections and approvals are set up in DPGatekeeper by a Gatekeeper administrator, who also gives the Frontline PSA application an identity that can request changes but can never approve them. If Gatekeeper is not configured in production, the Tenants screens show a configuration error; they never fall back to demo data. See Customer tenants.
Limits to plan for
Limit: Frontline PSA does not send email. There are no mail server settings. Messages the app queues are listed under Admin → Notifications.
Limit: There is no built-in backup. Back up the PostgreSQL database and the attachments directory with your own tools.
Limit: Attachments are limited to 25 MB each.