Skip to content

Installation (Self‑Hosted)

This chapter installs Scalio Nexus in your own environment using Docker Compose — the recommended and simplest method. After installing, you connect Microsoft with the Setup Wizard.

Applies to: Self‑Hosted

SaaS (managed) customers skip installation entirely — see Setup — SaaS (managed).

Prerequisites

  • A Linux or Windows host with Docker (version 24 or newer) and the Docker Compose plugin. On Windows, use Docker Desktop (WSL2 backend).
  • Outbound internet access to Microsoft 365 and to download the application images.
  • For hybrid (on‑premises AD) you also need a domain‑joined Windows machine for the agent — see Operation mode.

You do not need to install a database, a web server or any programming runtime — everything runs inside the containers.

What gets installed

Docker Compose starts three containers:

Container Role Reachable on
Web app The Scalio Nexus interface port 8080 (you can change it)
Application service Connects to Microsoft and the database internal only
Database Stores your configuration and audit history internal only (data kept in a named volume)

Step 1 — Get the deployment files

Place the deployment files — docker-compose.yml and a .env file — in a folder on the host, for example /opt/scalionexus. Your vendor provides these (or you clone the release repository).

Step 2 — Create the .env file

Next to docker-compose.yml, create a file named .env:

# A long, random secret used to protect sign-in sessions (required)
JWT_SECRET=replace-with-a-long-random-string

# Which released version (image tag) to run
APP_VERSION=latest

# Optional: your Pro license key. Without it the app runs in the free
# Community edition (up to 1 administrator and 25 employees).
# LICENSE_KEY=xxxxxxxx

Generate a strong secret:

openssl rand -hex 32

[guid]::NewGuid().ToString('N') + [guid]::NewGuid().ToString('N')

Keep .env private

It holds your session secret and, optionally, your license key. Never commit it to source control or share it.

Step 3 — Start it

From the folder that contains docker-compose.yml:

docker compose pull
docker compose up -d

Open http://<your-server>:8080 in a browser. The first account you create becomes the administrator.

For anything beyond local testing, run a reverse proxy (Caddy, Traefik or nginx) in front of the web app, terminate TLS there, and browse to your https:// address. Microsoft sign‑in and admin consent require an https address for anything other than localhost.

Step 5 — Connect Microsoft

Sign in and follow the Setup Wizard: choose Hybrid or Cloud‑Only, connect Microsoft Graph (generate a certificate, run the one‑time PowerShell script, grant admin consent), and optionally enable single sign‑on and Exchange Online. See Connection — Assistant vs Manual.

Updating

Self‑Hosted installations update themselves from Settings → Updates: when a new release is available (and covered by your license), one click downloads the new version and restarts the app. You can also switch on automatic updates. See Licensing & updates.

To update manually instead:

docker compose pull
docker compose up -d

Backups

Your configuration and audit history live in the database volume. Back it up on a schedule (and before major changes) using your platform's standard container/volume backup. The volume survives restarts and updates.

Everyday commands

docker compose ps            # container status
docker compose logs -f       # follow logs
docker compose down          # stop (keeps your data)
docker compose down -v       # stop and DELETE all data — use with care

Common issues

  • Can't reach the app — confirm port 8080 is open on the host firewall and not already in use; change the published port in docker-compose.yml if needed.
  • Microsoft sign‑in / consent fails — make sure you're using the app's real https address (not http) and that it matches what you registered in Entra. See Troubleshooting.
  • Stuck on the free‑edition limits — add a valid LICENSE_KEY to .env and run docker compose up -d again.