MSP Atlas
/

Chapter 9

Installing Atlas

Atlas runs as one Node.js service in front of PostgreSQL 16, behind HTTPS. There is no default administrator: you create the owner account with a one-time setup code. Pick the way that suits your server.

Way Best for Updates
Ubuntu or Debian installer Most MSPs. One command installs everything. From the Updates page in Atlas, with one click.
Docker Compose Teams that already run containers. Pull the new image and restart.
Windows Server A Windows-only environment. Extract the new package and run the script again.

Ubuntu or Debian

The installer sets up Node.js 22, PostgreSQL 16 and Caddy on Ubuntu 22.04 or 24.04, or Debian 12, builds Atlas, and runs it as a systemd service. It installs the newest published release, so these commands never need a version number. 

curl -fsSL https://raw.githubusercontent.com/ithealthtech/nexus-atlas/main/deploy/linux/install-atlas.sh -o install-atlas.sh
sudo bash install-atlas.sh --public-url https://atlas.example.com

The script prints the setup code when it finishes. It is also in journalctl -u msp-atlas.

Docker (Linux)

  1. Point a DNS name at the server, and open ports 80 and 443. Caddy uses them to get and renew the certificate.
  2. Copy .env.example to .env and set PUBLIC_URL, ATLAS_DOMAIN, POSTGRES_PASSWORD and ATLAS_MASTER_KEY. Generate the key with: 
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
  1. Start Atlas and read the setup code from the log:
docker compose -f deploy/docker-compose.yml --env-file .env up -d
docker compose -f deploy/docker-compose.yml logs app | grep "setup code"

A ready-built image is published for each release: ghcr.io/ithealthtech/nexus-atlas:1.7.32.

Windows Server

  1. Install Node.js 22 LTS and PostgreSQL 16, and create an empty database and user for Atlas.
  2. Download msp-atlas-1.7.32-windows.zip from the latest release, check it against the .sha256 file beside it, and extract it to a folder such as C:\Program Files\MSP Atlas.
  3. From an elevated PowerShell prompt, run:
.\deploy\windows\Install-Atlas.ps1 -PublicUrl https://atlas.example.com -DatabaseUrl "postgres://atlas:<password>@localhost:5432/atlas"

The script creates C:\ProgramData\MSP Atlas (readable only by Administrators and SYSTEM), creates the master key file on first install, and registers the MSPAtlas service to start automatically. The setup code is in C:\ProgramData\MSP Atlas\logs\MSPAtlas.out.log.

To upgrade, extract the new package over the old folder and run the script again with no arguments. It keeps your settings and key.

The master key

The master key protects every encrypted value: vault passwords, one-time code keys, MFA secrets, and the email, Hudu, ConnectWise and SIEM credentials. It also encrypts backups.

To rotate it, list the new key first and the old one after it, restart, run npm run rewrap-keys -w @atlas/server, then remove the old key. Keep the old key for as long as you keep backups made with it.

Your first day

  1. Create the owner account. Open Atlas, enter the setup code, and fill in your company and your own account.
  2. Turn on two-step verification when asked, and save the recovery codes somewhere other than Atlas.
  3. Back up the master key as described above.
  4. Set up email under Admin → Email & alerts, and choose Send test. Email is needed for password resets, expiry alerts and the weekly digest.
  5. Bring your data in from Hudu or spreadsheets under Admin → Import & export, or connect ConnectWise RMM. See Data and integrations.
  6. Invite your team and set their client access under Admin → People & access. See People and access.
  7. Check System status and make sure every check is green.

Where to go next