Install & set up

Install (fresh Debian 13 VM)

Prefer containers? See Install with Docker instead.

Recommended VM: 2 vCPU, 4 GB RAM, 20 GB disk, static IP, Debian 13 minimal with SSH.

1. On the VM (a minimal Debian may need apt install -y curl sudo first, as root):

curl -fsSL https://raw.githubusercontent.com/MSP-ALIGN/MSP-ALIGN/main/install.sh | sudo -E bash

2. Installing from a private fork? Create a fine-grained token limited to that repo with Contents: Read-only, then run read -rs GH_TOKEN && export GH_TOKEN first, add -H "Authorization: Bearer $GH_TOKEN" to the curl command, and set ALIGN_REPO=owner/name. The installer keeps the token in /etc/msp-align/github-token (root only) and uses it for updates. A fork installs only releases signed with a key in its deploy/release-signers: put your own key there (Signed releases), or leave the file with no key to follow the branch unsigned.

The installer asks for:

It installs Apache, PHP, MariaDB, git, age, fail2ban and ufw; creates the database (encrypted at rest), config and encryption key; turns on the firewall (SSH rate-limited, 80 and 443 open; in proxy mode only port 80 from the proxy; ALIGN_FIREWALL=0 leaves the firewall alone); bans addresses with repeated failed sign-ins (fail2ban, not in proxy mode); and sets up the site, the sync, PSA, email, nightly and update-check timers, the update and backup service and automatic security updates.

Proxy mode: point the proxy at http://<VM address>:80. It must pass the Host header and send X-Forwarded-For and X-Forwarded-Proto: https. For restores from the browser, allow request bodies up to 2 GB and a long timeout on /settings/system/upload (or restore from the command line). After changing the proxy's address in /etc/msp-align/config.php, run sudo msp-align-update so Apache and the firewall let the new address in, then remove the old one's firewall rule (sudo ufw status numbered, sudo ufw delete <number>).

Certificates: ITFlow and Veeam addresses must be https:// with a certificate this server trusts. For an internal certificate authority, copy its certificate to /usr/local/share/ca-certificates/ (as a .crt file) and run sudo update-ca-certificates.

Unattended install: set ALIGN_FQDN ALIGN_TLS ALIGN_ADMIN_EMAIL ALIGN_ADMIN_NAME ALIGN_TZ (plus ALIGN_LE_EMAIL or ALIGN_PROXY_IP when the TLS mode needs one, and GH_TOKEN for a private fork). With no terminal (cloud-init, a script) only ALIGN_ADMIN_EMAIL is required and the rest take the defaults in the table; run from a terminal, it still asks for anything not set, including the GitHub token. Optional: ALIGN_ADMIN_NAME, ALIGN_REPO=owner/name, ALIGN_BRANCH, ALIGN_FIREWALL=0 (leave ufw alone), ALIGN_DB_ENCRYPT=0 (no MariaDB encryption at rest), ALIGN_FORCE=1 (skip the Debian 13 check), ALIGN_RECONFIGURE=1 (rewrite the Apache site on an existing install: run the installer already on the server, sudo ALIGN_RECONFIGURE=1 bash /opt/msp-align/install.sh --upgrade, rather than a new download, so it stays on signed releases).

First-time setup

Integrations, Libraries, Staff & portal users, Settings and the Audit log are under your name (top right) → Administration (2.35.0).

1. Sign in with the password the installer printed. You'll be asked to choose your own password and set up two-factor sign-in (required). Store the backup decryption key the installer printed in your password manager, then run sudo shred -u /root/msp-align-backup-key.txt. You need it to restore any backup. Check it on Settings → Updates & backups → Check key. On a new install the setup wizard (1.40) then opens: company details and logo, currency & dates, PSA (or none), RMM, backups and warranty, email, your first clients and your team, one step at a time. Skip any step and come back to it from Settings → General; the steps below are the same settings done by hand.
2. Integrations → NinjaOne: Administration → Apps → API → Client app IDs → Add. Choose API Services (machine-to-machine), scope Monitoring, grant type Client credentials. Pick your NinjaOne Instance (US, US2, CA, EU or OC: the address you sign in to NinjaOne at). Align only reads from NinjaOne. Use Datto RMM instead, or as well? Integrations → Datto RMM (beta, 2.13.0): enable API access under Setup → Global Settings → Access Control, generate API keys for a user with a read-only security level that sees every site (Setup → Users), and pick the platform shown in that user's API URL. Align only reads from Datto. Use Tactical RMM instead, or as well? Integrations → Tactical RMM (beta, 2.11.0): make a Tactical user whose role has only List clients and List agents, for every client, add an API key for it under Settings → Global Settings → API Keys, and enter Tactical's API address (the one agents report to). Align only reads from Tactical.
3. Integrations → ITFlow: Admin → API Keys. The key runs as the ITFlow user you choose, so that user needs read access to Clients and Support (assets and tickets). It also needs read access to Contacts and Locations (for client addresses and phone numbers) Software and Vendors (for licensing), and Invoices (for the managed-services estimate), and write access to Support (assets) and Contacts for two-way sync and warranty write-back. Use HaloPSA instead? Integrations → HaloPSA (beta, 2.12.0): in Halo open Configuration → Integrations → HaloPSA API → View Applications → New, choose Client ID and Secret (Services), an agent that can see every client, and only the read:customers, read:assets and read:invoices permissions. Enter your Halo web address, the client ID and the secret. Align only reads from Halo. An install has one PSA, so set up ITFlow or HaloPSA, not both.
4. Optional: Integrations → Veeam Service Provider Console: in VSPC open Configuration → Security → REST API Keys and create a key for a read-only portal administrator. Enter the portal address (for example https://vspc.example.com; the API is /api/v3 on the same host) and the key. The certificate must be trusted by the Align server.
5. Optional: Integrations → Email: choose Microsoft 365, Google Workspace or an SMTP server. For Microsoft, Set up with Microsoft creates Align's own app after one admin sign-in (or register an Entra app yourself); for Google, a service account or OAuth client (the page walks through each) and pick the connection type; for SMTP, enter the server, port, security and sign-in. Send a test. Then choose which emails to send under Settings → Notifications.
6. Optional: Integrations → Dell TechDirect and Lenovo for automatic warranty dates.
7. Press Test connection on each integration (Send test for email), then Integrations → Sync history → Run sync now.
8. Client mapping: clients with matching names link automatically (NinjaOne organizations and Veeam companies); link the rest by hand.
9. Settings → Updates & backups → Download backup, and keep the file somewhere safe (file server, documentation system). Do this regularly; Align reminds you by email.
10. Optional: client portal. Make sure base_url in /etc/msp-align/config.php is the address clients will use (the installer sets it); invite links are built from it. Then open a client → Client portal → Invite user.

Updating

(Docker: download a backup, then docker compose pull && docker compose up -d; see Install with Docker.)

Settings → Updates & backups → Update to , or on the server:

sudo msp-align-update

Either one makes a safety copy, installs the newest release signed with the MSP Align release key (2.0; see Signed releases), or on a test server the latest code of its update_branch in config.php, installs any new packages, applies database migrations and reloads services. The safety copy is deleted once the update succeeds; if the installer fails and the update had no database changes, the previous version is put back. With nothing new, sudo msp-align-update installs the current release again (or a test server's current branch), which repairs packages, permissions and services. The server checks for updates every 6 hours by asking GitHub; to check a small version file first instead, add 'update_check_url' => 'https://mspalign.org/updates' to config.php (updates still download from GitHub). Servers on 1.13 or earlier: run the command once on the server to install the update and backup service; after that the page works.

Operations

Keep downloaded backups and the backup private key somewhere safe, and apart. A backup includes app_key (encrypted), which decrypts the stored API keys and 2FA secrets, so a restore on new hardware needs nothing else. Nightly backups on the server stopped in 1.14. Old ones in /var/backups/mountaineer-align/ stay until you delete them (the page offers to).

Something not working? See Troubleshooting, and the FAQ for common questions.