Installation & Deployment

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.

Windows Installation (MSI)

The standard tracking and deployment method for enterprise environments.

1. Request Download

• Navigate to the Pricing Section on our website.
• Select the tier that fits your needs (or the Free Home Lab tier).
• Check your Email: You will receive an email containing a link to your LemonSqueezy Order Portal.
• Click the Download App button in your portal to retrieve the latest StacksAtlas.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:

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

5. Launch & SSL Warning

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

• Your browser will open to https://localhost:5001.
• SSL Warning: You will see a "Connection is not private" warning.
  • Why? The appliance generates a distinct, self-signed certificate for your local network.
  • Action: Click Advanced and select Proceed to localhost (unsafe).

6. Establishing Permanent SSL Trust

To eliminate browser warnings and satisfy security audits:

1. Navigate to Settings > System & Network.
2. Click Download SSL Certificate (Trust this Appliance).
3. Install the certificate to your Trusted Root Certification Authorities store.
4. Restart your browser. The connection will now show as Secure (Green Lock).

7. Dynamic Port Management

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

1. Go to Settings > System & Network.
2. Update the HTTP or HTTPS port fields.
3. Click Restart & Apply.
4. The engine will migrate your configuration and restart gracefully.

Deploying via Docker (Linux & NAS)

We provide a natively compiled Docker container to allow deployments across Ubuntu, Debian, Unraid, TrueNAS, and Synology architectures.

The image is automatically built and tested through GitHub Actions via our public CI/CD pipeline and served directly from the GitHub Container Registry (ghcr.io).

1. Pull the Image

docker pull ghcr.io/keatonstacks/stacksatlas:latest

2. Deploy via Docker Compose (Recommended)

Docker Compose is the most reliable way to manage persistent data and environment variables. Create a docker-compose.yml file:

version: '3.8'
services:
  stacksatlas:
    image: ghcr.io/keatonstacks/stacksatlas:latest
    container_name: stacksatlas
    network_mode: host
    restart: unless-stopped
    environment:
      - STACKSATLAS_PORT=5000
      - STACKSATLAS_HTTPS_PORT=5001
    volumes:
      - /opt/stacksatlas/data:/app/data

3. Deploy via Docker Run

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 (Native API)

StacksAtlas is natively compiled for both Apple Silicon (osx-arm64) and Intel (osx-x64) Macs. Running it natively ensures StacksAtlas has absolute access to the physical Wi-Fi or Ethernet adapter for Layer-2 Network Discovery.

1. Request Download

• Navigate to the Pricing Section on our website.
• Select a tier (or the Free Home Lab tier).
• Check your Email: You will receive an order confirmation linking to your LemonSqueezy Order Portal.
• In your portal, download the correct Universal Zip for your architecture (Apple Silicon arm64 or Intel x64).

2. Install & Run

Extract the .zip archive to your Applications folder and launch the daemon via your terminal:

unzip StacksAtlas-osx-*.zip -d /Applications/StacksAtlas
cd /Applications/StacksAtlas
sudo ./StacksAtlas.API

Note: StacksAtlas must be run via sudo on macOS to bind to Port 5000/5001 and access raw libpcap capabilities for network discovery.