Navigation
18.1. Self-Hosting AlgaPSA: The On-Premise Appliance
Run AlgaPSA on your own hardware with the on-premise appliance. What the appliance is, who it suits, the prerequisites you need, and the four stages of a clean install.
The AlgaPSA appliance lets you run the full platform on infrastructure you control: your own server, your own hypervisor, or a VM in your data center. You keep your PSA data on-site. You decide when the platform updates. It fits MSPs who have compliance requirements, serve clients that expect on-premise systems, or want to own the stack end to end.
The appliance ships as a single bootable image. It installs Ubuntu, brings up a self-contained Kubernetes runtime, and deploys AlgaPSA and its supporting services (database, cache, background workers, and email processing) for you. You do not assemble containers or write manifests. You boot the image, answer a short setup wizard, and sign in.
The screenshots throughout follow a fictional MSP, Northpoint Technology Group, and its first client. Use them as a model for your own company, team, and client details.
What you get
| Component | What it does |
|---|---|
| AlgaPSA application | The web app your team signs in to, served on port 3000. |
| Setup, status, and management console | A separate web console on port 8080 for first-time setup, ongoing health, and supported appliance management tasks such as pod terminal and port-forward access. |
| In-cluster database, cache, and workers | Postgres, Redis, Temporal, and the workflow and email workers, all managed for you. |
| Temporal-backed provisioning | The setup workflow redeems the install code, provisions the tenant and first administrator, pulls the required images, runs migrations, and reconciles the application services. |
The appliance is self-managing once it is up. You work in the application on port 3000. You check its health on port 8080 when you need to.
Editions and the install code
When you register, you receive an install code by email. The code binds the appliance to your tenant and applies the correct edition, so you do not pick an edition during setup.
- Essentials runs the free, open-source feature set. The application offers a 15-day Pro trial you can start at any time from inside the app.
- Paid editions include the full feature set for self-hosting.
Keep the registration email handy. You enter the install code once, in the setup wizard.
Before you start
Check these prerequisites before you boot the image. They keep the install from stalling partway through.
| Requirement | Recommendation |
|---|---|
| Host | A 64-bit x86 machine or virtual machine. The appliance image is Ubuntu Server 24.04. |
| CPU and memory | A practical starting point is 4 vCPUs and 16 GB of RAM. The appliance runs a database, cache, workers, and the application together. |
| Disk | At least 60 GB. The installer uses the whole disk you select. |
| Network address | A reachable IPv4 address. If you use DHCP, reserve the lease so the address does not change after a reboot. |
| Outbound internet | HTTPS (port 443) to license.nineminds.com and ghcr.io. The appliance redeems your install code and pulls its container images during setup. Mobile push notifications (sent via the AlgaPSA mobile app) also require outbound HTTPS to exp.host; if this host is unreachable, push alerts will not be delivered and the mobile app will report "Expo unreachable" when testing notifications from Settings. For phone registration and the test notification workflow, see 22.1. Install AlgaPSA Mobile and Sign In. |
| Install code | The 8-character code from your AlgaPSA registration email. |
Outbound access matters most. During setup the appliance contacts license.nineminds.com to redeem the install code. It then pulls its images from GitHub Container Registry (ghcr.io). If a firewall blocks either host, setup pauses at the redemption or image-pull step until you open the access.
The four stages
A full install moves through four stages. Each has its own guide.
- Install the operating system. Boot the image, set up networking and disk, create the host account, and read the setup handoff banner.
- Configure the appliance. Open the setup console, enter your install code and first tenant/admin details, then start the Temporal-backed provisioning workflow.
- Sign in and onboard. Sign in to the application and complete the guided onboarding for your team, your first client, billing, and ticketing.
- Operate. Use AlgaPSA on port 3000, and check the status console on port 8080 when you need to.
Set aside roughly 30 to 45 minutes for a first install. The appliance deploys unattended for most of that time.
Integrations that need an app registration you own
Hosted AlgaPSA ships with shared Microsoft and Intuit app registrations, so hosted tenants connect Microsoft 365 and QuickBooks Online with a sign-in and nothing else. A self-hosted appliance has no shared registrations. For these two integrations you create the registration once, in the vendor's developer portal, and enter its client ID and client secret in AlgaPSA:
| Integration | What you register | Where the steps are |
|---|---|---|
| Microsoft 365 inbound email | A Microsoft Entra app registration | Set Up Email on the Appliance |
| QuickBooks Online | An Intuit app on developer.intuit.com | Connect QuickBooks Online, Step 2 |
In both cases AlgaPSA shows you the exact redirect URI to register. Everything else about those integrations works the same as on hosted AlgaPSA.
Provision a custom client-portal domain
Self-hosted Community Edition installs can provision a custom client-portal domain, such as portal.northpoint.example. This is also supported on the AlgaPSA Appliance. The operator manages DNS, the reverse proxy, and the domain's TLS certificate.
- Choose a portal hostname different from your MSP app hostname. Point its DNS at your server using an A record or a CNAME to the server's hostname.
- Configure your reverse proxy to terminate TLS for the portal hostname and forward requests to the AlgaPSA application on port 3000. Preserve the original Host header and send X-Forwarded-Proto: https.
- If the proxy rewrites Host, have it forward the original hostname in X-Forwarded-Host and set
TRUST_FORWARDED_HOST=truein the AlgaPSA application environment. This is sufficient for forwarded-host handling on a Community Edition install. - In the MSP app, open Settings > Client Portal and find Custom Domain. Enter the hostname in Custom domain, then select Save Domain.
- Confirm Active, then open the bare portal address in a new browser session. Its root leads to the client portal, including the sign-in flow for an unauthenticated client.
Saving activates the domain immediately and portal links start using it, so complete DNS and proxy setup before saving. The Active status records the application's domain configuration; check the certificate, portal sign-in, and a portal invitation link to verify that clients can actually reach it. If no requests reach the domain, review whether the proxy preserves or forwards the original hostname.
Licensing after the install
The appliance runs the free Essentials edition out of the box, with a 15-day Pro trial you can start any time from Settings → License. Buying Pro, changing seat counts, and recovering activation codes or offline keys all happen in the licensing portal, which signs you in with a link sent to your registered email address. Licenses issued there are activated on the appliance's License page.
For an operational check, open Manage in the appliance console on port 8080. The licensed edition comes from the license token, so a Pro license reads Pro. If the application cannot be reached, the console identifies live license status as unavailable and shows the last activation record when available, separately from an application reporting no license.
On appliances, Microsoft or Google SSO configured through a provider profile reports as available and links to the configured provider. These providers require Enterprise Edition; Community Edition uses Keycloak. See 10.18. Set Up SSO with Keycloak, Google Workspace, or Microsoft 365 for staff sign-in configuration.