Frontline PSA Docs

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

ComponentRequirement
RuntimeNode.js 22.9 or later, or Docker
DatabasePostgreSQL 16 or later. A local trial uses an embedded database (PGlite) instead and needs nothing installed.
Sign-inCloudflare Access in front of the app (production)
File storageA persistent directory for attachments
OptionalAn OpenAI-compatible AI gateway, a DPMem service, and DPGatekeeper for customer tenants

Try it locally

A trial needs no configuration.

  1. Install the dependencies with npm install.
  2. Start the app with npm run dev.
  3. 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

  1. Create an empty PostgreSQL database.
  2. Copy .env.example to .env and set at least NODE_ENV=production, DATABASE_URL, CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD.
  3. Set PSA_BOOTSTRAP_ADMIN_EMAIL to your own email for the first start (see below).
  4. Build the app with npm run build.
  5. Create the database tables with npm run db:migrate.
  6. 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 /healthz without 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_DOMAIN and CF_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:

PathUsed 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

VariablePurpose
NODE_ENVSet to production. A built server started without it is also treated as production.
DATABASE_URLPostgreSQL connection string. If unset, the embedded database is used.
CF_ACCESS_TEAM_DOMAINYour Cloudflare Access team domain, for example yourteam.cloudflareaccess.com.
CF_ACCESS_AUDThe AUD tag of the Access application.
ATTACHMENTS_DIRWhere uploaded files are stored. Default ./data/attachments.
BODY_SIZE_LIMITLargest request the server accepts. npm start and the Docker image set 26M so that 25 MB attachments fit.
PSA_BOOTSTRAP_ADMIN_EMAILEmail of the first administrator, used only on an empty database.
PSA_BOOTSTRAP_ADMIN_NAME, PSA_COMPANY_NAME, PSA_TIMEZONEName of that administrator, your company name and your time zone for the first start.
PSA_AUTO_MIGRATESet to 1 to apply database changes at startup.

AI triage and Scout

VariablePurpose
LITELLM_BASE_URL, LITELLM_API_KEYAddress and key of an OpenAI-compatible AI gateway. With a key set, AI runs live.
AI_MODElive, mock or off. In production the default is off until a key is set.
AI_MODEL, AI_FAST_MODELModel names to request from the gateway.
AI_MAX_TOKENS, AI_TIMEOUT_MSLimits for each model call.
SCOUT_DISPATCHmanual in production: the technician runs the launcher on the device.
SCOUT_PUBLIC_URLThe address customer devices use to reach Frontline PSA.
SCOUT_LEDGER_KEYSecret used to sign the Scout ledger. Set it in production and keep it safe.
SCOUT_AGENT_NO_SHOW_SECONDSHow long a session waits for the agent to connect. Default 900 in production.

See AI triage and Scout.

Customer memory (DPMem)

VariablePurpose
PALACE_MODElive, mock or off. In production the default is off until fully configured.
PALACE_URLAddress of the DPMem service.
PALACE_CERT_FILE, PALACE_KEY_FILEClient certificate and key. Both are required, together with the API key.
PALACE_API_KEYAPI key for the DPMem service.
PALACE_SHARED_NAMESPACEName 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)

VariablePurpose
GATEKEEPER_MODEmock or live. Production always runs live.
GATEKEEPER_URLAddress 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_SCOPEThe Microsoft Entra application Frontline PSA uses to identify itself to Gatekeeper. Set all four.
GATEKEEPER_TOKEN_FILE, GATEKEEPER_TOKENAlternatives to Entra: a token read from a file, or a fixed token.
GATEKEEPER_CONSOLE_URLAddress 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.