Installation & Deployment

Name: StacksAtlas
Brand: StacksAtlas

StacksAtlas is distributed as an enterprise-ready MSI installer, simplifying deployment across Windows environments.

System Requirements

StacksAtlas is lightweight and designed to run alongside other server applications.

Component	Minimum	Recommended
Operating System	Windows 10 / macOS 12 / Docker	Windows Server / Apple Silicon / NAS
Processor	Dual-Core 2.0 GHz	Quad-Core (for large subnets)
Memory (RAM)	2 GB	4 GB
Storage	500 MB	10 GB (for log retention)
Network	100 Mbps NIC	1 Gbps Ethernet

Free Portable (Windows, macOS, Docker)

No license key required. Session scanner with unlimited discovery and security grades: upgrade to Business when you need always-on monitoring and a persistent database.

Windows Portable

Download StacksAtlas-Portable.exe from the home page or releases.stacksatlas.com/stable/win-x64-portable.
Double-click (no admin). Tray icon appears; browser opens http://127.0.0.1:5000/onboarding.
Close & remove from the tray or avatar menu wipes %LOCALAPPDATA%\StacksAtlas\.

macOS Portable

Download the universal DMG from the home page.
Mount DMG, then open StacksAtlas.app (Developer ID signed and notarized; no “unidentified developer” on current releases).
Run without Install StacksAtlas.app. Browser opens http://127.0.0.1:5050/onboarding (macOS uses 5050 because Monterey+ reserves 5000 for AirPlay).
Data lives in ~/StacksAtlas-Trial until you choose Close & remove portable data from the avatar menu.

Docker Portable (Free)

Free session scanner on a Linux box or NAS. No license key. Same download image as Business.

1. Pull the image: docker pull ghcr.io/keatonstacks/stacksatlas:latest
2. Save the file below as docker-compose.yml on your NAS (for example /opt/stacksatlas/docker-compose.yml).
3. Create the data folder: mkdir -p /opt/stacksatlas/data
4. Start: cd /opt/stacksatlas && docker compose up -d
5. Open http://YOUR-NAS-IP:5000/onboarding from any PC on your network.
6. When finished testing: docker compose down -v removes session data.

services:
  stacksatlas-portable:
    image: ghcr.io/keatonstacks/stacksatlas:latest
    container_name: stacksatlas-portable
    network_mode: host
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - NET_RAW
    environment:
      - STACKSATLAS_PORTABLE=1
      - STACKSATLAS_PORTABLE_BIND_LAN=1
      - STACKSATLAS_DATADIR=/app/data
    volumes:
      - /opt/stacksatlas/data:/app/data

Discovery and security grades work immediately: no Nmap required. If you see an optional Deep Scan notice in the dashboard, click Discovery is enough. For port-level Deep Scan later, see Optional Deep Scan.

What portable includes (and excludes)

Portable is a session scanner: full discovery, security grades, and reports while the app is open. It is not the always-on Business appliance.

Capability	Free portable	Business
Unlimited device discovery
Persistent database & history
Subnet discovery & security grades
Deep Scan (optional Nmap)	If you install Nmap	If you install Nmap
PDF reports & CSV export (session)
Always-on background scanning
Alerts, webhooks & SMTP
Multi-user accounts & RBAC
SSO / LDAP
Hub & fleet federation
Syslog / SIEM export
In-appliance updates (Windows)	One-click apply	MSI + portable apply
License key required	No	Yes (Business)

Upgrade to Business when you need alerts, multi-user access, SSO, federation, or a background service that survives logoff and reboot.

Most people can skip this page

StacksAtlas already discovers devices on your network, grades security, and builds reports without Nmap. If the dashboard shows a notice about Deep Scan, click Discovery is enough and keep going.

Deep Scan is optional. It adds per-device port and operating-system detail using Nmap. We do not ship Nmap inside the official download (license). Install it yourself only if you want that extra detail.

Windows

1. Download the installer from nmap.org/download (includes Npcap).
2. Run the installer. Enable WinPcap API-compatible mode when Npcap asks.
3. Restart StacksAtlas if it was already open.

macOS

In Terminal: brew install nmap, then restart StacksAtlas.

Docker / Linux NAS (Unraid, TrueNAS, Ubuntu, etc.)

You already pulled the image (for example docker pull ghcr.io/keatonstacks/stacksatlas:latest). Discovery works with that image. To add Deep Scan, you build a second local image tag on your NAS that adds Nmap on top. The build usually takes about one minute.

Step 1: On your NAS (SSH or terminal), create a folder and a small Dockerfile

Pick wherever you keep your compose file (example: /opt/stacksatlas). Run:

mkdir -p /opt/stacksatlas/stacksatlas-build
nano /opt/stacksatlas/stacksatlas-build/Dockerfile

Paste this entire file, save, and exit:

FROM ghcr.io/keatonstacks/stacksatlas:latest
USER root
RUN apt-get update \
    && apt-get install -y --no-install-recommends nmap \
    && rm -rf /var/lib/apt/lists/*

Step 2: Update your docker-compose.yml

Open the compose file you already use for StacksAtlas. Find the stacksatlas service and make sure it includes build: and image: stacksatlas:deep-scan like below. Keep your existing volumes and paths (the example uses /opt/stacksatlas/data).

services:
  stacksatlas:
    build:
      context: ./stacksatlas-build
      dockerfile: Dockerfile
    image: stacksatlas:deep-scan
    container_name: stacksatlas
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - /opt/stacksatlas/data:/app/data

Free portable Docker? Use the same build: block on your stacksatlas-portable service and set image: stacksatlas:deep-scan. Keep STACKSATLAS_PORTABLE=1 and STACKSATLAS_PORTABLE_BIND_LAN=1 as you already have.

Step 3: Build and start

cd /opt/stacksatlas
docker compose up -d --build

Step 4: Confirm Nmap is there

docker exec stacksatlas nmap --version

You should see a version number (for example Nmap 7.94). The dashboard notice should clear after a refresh.

After you update StacksAtlas

When you docker pull a newer release, run docker compose up -d --build once so the Nmap layer rebuilds on top of the new base image.

Still stuck? See Deep Scan troubleshooting or Settings → Scanning for engine status.

Windows Installation (MSI: Business)

Requires a Business license ($40). The always-on Windows Service appliance.

1. Purchase & Download

Purchase Business from the pricing section.
Check your email for the Lemon Squeezy order portal and license key.
Download StacksAtlas.msi from the portal or releases.stacksatlas.com/stable/win-x64-msi.

2. Browser Warnings (Keep File)

Because our installer is updated frequently, your browser might flag it as "Uncommonly Downloaded".

Edge/Chrome: You may see a warning that the file "could harm your device".
1. Hover over the download.
2. Click the Three Dots (...) menu.
3. Select Keep.
4. Select Keep Anyway to finish the download.

3. Run Installer & SmartScreen

Double-click the StacksAtlas.msi file.

Windows SmartScreen: You will likely see a blue window saying "Windows protected your PC".
- Why? We are building our reputation with the certificate authority.
- Action: Click More Info, then click the Run Anyway button.

4. Automated Setup

The installer performs the following actions automatically:

Service Registration: Installs the background service (StacksAtlas) set to Automatic (Delayed Start).
Firewall: Configures Windows Defender Firewall rules for Ports 5000 (HTTP) and 5001 (HTTPS).
Shortcuts: Creates a "StacksAtlas" shortcut on your Desktop.

5. Launch & First Run (v1.7.5+)

At the end of installation, ensure "Launch StacksAtlas" is checked and click Finish.

Your browser will open to http://127.0.0.1:5000/onboarding (HTTP-first: no certificate warning).
An optional onboarding step lets you trust the local CA for HTTPS on port 5001.
Linux / Docker / Mac: Use http://127.0.0.1:5000 (Docker/Windows) or http://127.0.0.1:5050 (macOS) on first launch.

6. Manual SSL Trust (optional)

For security audits or if you skipped optional certificate trust during onboarding (e.g. you did not click Launch on Finish):

Navigate to Settings → Infrastructure.
Click Download TLS Certificate.
Install the certificate to your Trusted Root Certification Authorities store.
Restart your browser.

7. Dynamic Port Management

Starting in v1.2.3, you can change the default 5000/5001 ports directly from the UI:

Go to Settings → INFRASTRUCTURE.
Update the HTTP or HTTPS port fields.
Click Restart & Apply.
The engine will migrate your configuration and restart gracefully.

Deploying via Docker (Business Appliance)

Always-on Linux/NAS deployment. Requires a Business license ($40). Download the image from releases.stacksatlas.com or pull from GHCR: ghcr.io/keatonstacks/stacksatlas:latest.

For a free trial on Docker, see Docker Portable (free) above.

Network host mode required

StacksAtlas must run with network_mode: host (or --network host) so the discovery engine can perform raw Layer-2 ARP and ICMP on your LAN. Bridge networking isolates the container and causes ghost or missing devices.

1. Pull the image

docker pull ghcr.io/keatonstacks/stacksatlas:latest

2. Create docker-compose.yml on your NAS

Save this as /opt/stacksatlas/docker-compose.yml (adjust the data path if you use a different folder):

services:
  stacksatlas:
    image: ghcr.io/keatonstacks/stacksatlas:latest
    container_name: stacksatlas
    network_mode: host
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - /opt/stacksatlas/data:/app/data

Then:

mkdir -p /opt/stacksatlas/data
cd /opt/stacksatlas
docker compose up -d

Open http://YOUR-SERVER-IP:5000 or https://YOUR-SERVER-IP:5001, complete onboarding, and enter your Business license in Settings.

Optional Deep Scan (Nmap): not included in the default image. See Optional Deep Scan: copy/paste setup, no source code required.

Updating Docker Business

StacksAtlas does not auto-update inside the container. Choose a path by role:

Situation	Recommended path
Standalone Docker Business with internet	Host-side Watchtower (below) or manual `docker pull` + `docker compose up -d --force-recreate`
Enrolled Node (Hub is the internet door)	Hub stages once; Node checks Hub depot; host runs guided pull/recreate. Do not point Watchtower at public GHCR for air-gap control.
Free portable	No auto-update (session scanner)

Pin a version tag for preview builds (ghcr.io/keatonstacks/stacksatlas:1.9.4). The GHCR :latest tag moves only when a stable release is published. Fleet depot UI: Infrastructure → Software updates.

Watchtower (standalone Docker Business)

Watchtower runs on the Docker host as a compose sidecar (not inside the StacksAtlas image). It polls the registry and recreates the stacksatlas container when a newer image appears. Bind-mounted data is preserved.

Use when: standalone Business host that can reach ghcr.io.
Do not use when: Hub-enrolled air-gap Node (use Hub depot) or portable session mode.

Merge this service into the same compose project as stacksatlas (container name must match the last command argument):

services:
  watchtower:
    image: containrrr/watchtower:1.7.1
    container_name: stacksatlas-watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command:
      - --cleanup
      - --interval
      - "3600"
      - stacksatlas

cd /path/to/your/compose
docker compose up -d watchtower
docker logs -f stacksatlas-watchtower

Private GHCR: docker login ghcr.io once on the host. Prefer a version tag until stable promote moves :latest. Preview-only publishes are not visible on :latest.

Deep Scan image: if compose uses image: stacksatlas:deep-scan, either rebuild after base pulls (docker compose up -d --build --force-recreate stacksatlas) or skip Watchtower and update manually.

Enrolled Docker Node (Hub depot)

Docker cannot one-click apply inside the container. Hub Notify only tells the site an update is ready. You run pull (or load) + recreate on the Linux host.

Before you recreate: check image: in compose.

Your compose	After docker pull + tag to stacksatlas:latest
`image: stacksatlas:latest` (no `build:`)	`docker compose up -d --force-recreate stacksatlas`
`image: stacksatlas:deep-scan` with `build:` (Nmap layer)	`docker compose build --no-cache stacksatlas` then `docker compose up -d --force-recreate stacksatlas` (or one shot: `up -d --build --force-recreate`)

If you only --force-recreate on a Deep Scan host, the container keeps the old stacksatlas:deep-scan image and the UI still shows the previous version (classic footgun).

On the Hub: preview on (for preview builds) → Stage → Notify update / Update now for the Linux site.
On the Node UI: open the Hub banner (or Check for updates with the same channel). Prefer the host commands shown under Host Docker update.
SSH to the Docker host (replace 1.9.4 with the version the UI reports):

Deep Scan (homelab default when you added Nmap):

docker pull ghcr.io/keatonstacks/stacksatlas:1.9.4
docker tag ghcr.io/keatonstacks/stacksatlas:1.9.4 stacksatlas:latest
cd ~/docker-main
docker compose build --no-cache stacksatlas
docker compose up -d --force-recreate stacksatlas
# Confirm in Node UI → Settings → INSTALLED VERSION

Plain Business image (no build:):

docker pull ghcr.io/keatonstacks/stacksatlas:1.9.4
docker tag ghcr.io/keatonstacks/stacksatlas:1.9.4 stacksatlas:latest
cd ~/docker-main
docker compose up -d --force-recreate stacksatlas

Air-gap / no GHCR: docker load -i StacksAtlas-Docker.tar, tag as stacksatlas:latest, then the Deep Scan or plain recreate path above. Do not run public Watchtower on Hub-enrolled air-gap Nodes.

Homelab shortcut from the Windows build machine: ./deploy-dev.ps1 -Linux -PullGhcr -GhcrVersion 1.9.4 (still rebuild Deep Scan on the host if compose has build:).

3. One-line docker run (alternative)

If you prefer a one-liner, ensure you use the --network host flag and map your data volume.

docker run -d \
  --name stacksatlas \
  --network host \
  --restart unless-stopped \
  -e STACKSATLAS_PORT=5000 \
  -e STACKSATLAS_HTTPS_PORT=5001 \
  -v /opt/stacksatlas/data:/app/data \
  ghcr.io/keatonstacks/stacksatlas:latest

Once running, StacksAtlas will immediately begin initialization! Access your local network instance at https://<YOUR_LINUX_IP>:5001.

Deploying on macOS (Business Install)

Universal DMG with Install StacksAtlas.app (always-on LaunchDaemon + menu bar). Requires a Business license.

1. Purchase & Download

Purchase Business from pricing.
Download the universal DMG from your Lemon Squeezy portal or releases.stacksatlas.com/stable/osx-universal-dmg.

2. Install & Run

Mount the DMG and run Install StacksAtlas.app (admin password once).
Use the menu bar companion to open the dashboard.
Default HTTP port on Mac is 5050: http://127.0.0.1:5050/onboarding.

For free portable, run StacksAtlas.app from the DMG without Install: see Free Portable above.

StacksAtlas + OpenAVC stack (Business, optional)

Room-control sites often run StacksAtlas (discovery + security) and OpenAVC (drivers + macros) on the same LAN. Install both appliances on the site Node, then configure Settings → OPENAVC before linking devices from the inventory Controls tab.

Two-appliance quick start

Step-by-step install, credentials, linking, and macro pins: Integrations → OpenAVC Control Bridge. Not available in portable try mode.

Software updates (Business, Windows)

StacksAtlas can upgrade itself from releases.stacksatlas.com using a signed release manifest (Ed25519). No GitHub account required.

Where to check

Sign in as an Admin.
Open Settings → Infrastructure → Software Updates.
Choose stable or preview channel and click Check for updates.

One-click apply (Windows)

MSI appliance: Download & Install runs a quiet MSI upgrade. A database snapshot is taken before apply.
Portable EXE: Download & Install replaces the launcher with a backup (.pre-update.bak). No LiteDB snapshot on portable.

The header may show an update chip when a newer build is published. You can snooze reminders for seven days.

Other platforms

macOS: Update check is supported; apply is manual (download a new DMG from your portal or CDN).
Docker: See Updating Docker Business (Watchtower or Hub depot). In-appliance one-click apply is Windows-only today.
Hub fleets: Stage on the Hub, notify Nodes, confirm locally. Details: Infrastructure → Software updates.

Trust

Manifest signatures are verified before download. Windows MSI and portable builds are Authenticode-signed (STACKSATLAS LLC). macOS DMG builds are Developer ID signed and notarized (v1.7.6+).

Getting started