Installation

Overview

NetStacks ships as two components that you can install independently depending on your workflow:

• NetStacks Terminal -- a native desktop application for connecting to network devices via SSH and Telnet. Available for macOS (Intel and Apple Silicon), Windows (x64), and Linux (x64 and ARM).
• NetStacks Controller -- a Docker-based server that adds centralized device inventory, credential vault, session recording, and team management. Optional for individual use, required for enterprise deployments.

Most users start with Terminal only (standalone mode). You can add the Controller later when you need centralized management for a team or want features like SSH certificate authentication and audit logging.

How It Works

Terminal is built with Tauri, which packages a Rust backend with a lightweight webview frontend into a native binary for each platform. The distribution format varies by OS:

• macOS -- DMG disk image containing NetStacks.app
• Windows -- MSI installer or NSIS setup executable
• Linux -- AppImage (universal) or .deb package (Debian/Ubuntu)

Terminal includes a built-in auto-updater powered by the Tauri updater plugin. When a new version is available, Terminal prompts you to download and install it without leaving the application.

Controller runs as two Docker containers orchestrated by Docker Compose: an Axum-based Rust API server and a PostgreSQL 16 database with the pgvector extension. Updates are applied by pulling new container images and restarting the stack.

Step-by-Step Guide

Choose the section that matches your platform. If you are deploying the Controller for your team, follow the Docker Compose instructions after installing Terminal.

macOS (Intel and Apple Silicon)

NetStacks provides separate DMG installers for each Mac architecture. Choose the right one for your processor:

• Apple Silicon (M1/M2/M3/M4) -- NetStacks-aarch64.dmg
• Intel -- NetStacks-x64.dmg

1. Download the appropriate DMG from the downloads page.
2. Open the DMG file and drag NetStacks.app into your Applications folder.
3. Launch NetStacks from Applications or Spotlight. On first launch, macOS Gatekeeper will block the app because it is not notarized through the App Store. Right-click (or Control-click) the app and select Open, then click Open in the confirmation dialog.
4. Verify the Terminal launches and displays the welcome screen.

xattr -cr /Applications/NetStacks.app

Windows (x64)

Two installer options are available for Windows:

• MSI Installer -- NetStacks-x64.msi (recommended for most users and enterprise deployment via Group Policy)
• NSIS Setup -- NetStacks-x64-setup.exe (alternative installer with custom install directory support)

1. Download the MSI or NSIS installer from the downloads page.
2. Double-click the installer and follow the wizard. The default install location is C:\Program Files\NetStacks.
3. Launch NetStacks from the Start Menu or the desktop shortcut created by the installer.
4. Verify the Terminal launches and displays the welcome screen.

Linux (x64 and ARM)

NetStacks is distributed in two formats for Linux. Both x64 and ARM (aarch64) builds are available:

• AppImage -- universal, runs on any distribution without installation
• .deb package -- for Debian, Ubuntu, and derivatives

AppImage

# Download the AppImage for your architecture
# x64:   NetStacks-x64.AppImage
# ARM64: NetStacks-aarch64.AppImage

chmod +x NetStacks-*.AppImage
./NetStacks-*.AppImage

Debian/Ubuntu (.deb)

# Install the .deb package
sudo dpkg -i netstacks_*_amd64.deb

# If dependencies are missing, fix them
sudo apt-get install -f

After installing the .deb package, launch NetStacks from your application menu or run netstacks from a terminal.

Controller (Docker Compose)

The Controller is deployed as a Docker Compose stack. Starting with v0.0.9, the Controller ships as two separate Docker images: controller-api (Rust API server) and controller-admin (Nginx serving the React admin dashboard). This enables independent scaling of the API and admin interface. The stack also requires a PostgreSQL 16 database with pgvector. For high-availability deployments, an optional Valkey container provides cross-instance session coordination (see HA Deployment).

Prerequisites

• Docker Engine 20.10 or later
• Docker Compose v2 (the docker compose subcommand, not the legacy docker-compose binary)
• 2 GB RAM minimum (4 GB recommended)
• 10 GB available disk space

Step 1: Create a project directory

mkdir netstacks-controller && cd netstacks-controller

Step 2: Create docker-compose.yml

Create the following docker-compose.yml in your project directory. This is the same file used by the NetStacks team for production deployments:

services:
  db:
    image: pgvector/pgvector:pg16
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-netstacks}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-netstacks_dev}
      POSTGRES_DB: ${POSTGRES_DB:-netstacks}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U netstacks"]
      interval: 5s
      timeout: 5s
      retries: 5

  api:
    build:
      context: .
      dockerfile: Dockerfile
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER:-netstacks}:${POSTGRES_PASSWORD:-netstacks_dev}@db:5432/${POSTGRES_DB:-netstacks}
      VAULT_MASTER_KEY: ${VAULT_MASTER_KEY:-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef}
      JWT_SECRET: ${JWT_SECRET:-dev_secret_change_in_production}
      SERVICE_TOKEN_SECRET: ${SERVICE_TOKEN_SECRET:-dev_service_token_secret_change_in_production}
      HOST: ${HOST:-0.0.0.0}
      API_PORT: ${API_PORT:-3000}
      RUST_LOG: ${RUST_LOG:-info,netstacks_api=debug}
      NETSTACKS_MODE: ${NETSTACKS_MODE:-enterprise}
      JUMPBOX_ENABLED: ${JUMPBOX_ENABLED:-true}
      JUMPBOX_IMAGE: ${JUMPBOX_IMAGE:-netstacks-jumpbox:latest}
      PLUGIN_NETWORK: ${PLUGIN_NETWORK:-controller_default}
      NETSTACKS_KNOWN_HOSTS_PATH: ${NETSTACKS_KNOWN_HOSTS_PATH:-/data/known_hosts}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - netstacks_data:/data

  admin:
    image: ghcr.io/netstacks/controller-admin:latest
    ports:
      - "8080:80"
    depends_on:
      - api

  # Optional: Valkey for HA multi-instance deployments
  # See /docs/admin/ha-deployment for configuration details
  # valkey:
  #   image: valkey/valkey:8-alpine
  #   ports:
  #     - "6379:6379"
  #   volumes:
  #     - valkey-data:/data
  #   command: valkey-server --appendonly yes

volumes:
  pgdata:
  netstacks_data:

Step 3: Create a .env file with production values

# Generate secure values for each secret
openssl rand -hex 32    # Use output for VAULT_MASTER_KEY
openssl rand -base64 48 # Use output for JWT_SECRET
openssl rand -base64 48 # Use output for SERVICE_TOKEN_SECRET

# .env -- place in the same directory as docker-compose.yml

POSTGRES_PASSWORD=<strong-database-password>
VAULT_MASTER_KEY=<64-hex-char-key-from-openssl>
JWT_SECRET=<base64-string-from-openssl>
SERVICE_TOKEN_SECRET=<base64-string-from-openssl>

# Optional overrides
# API_PORT=3000
# RUST_LOG=info,netstacks_api=debug

Step 4: Start the stack

docker compose up -d

Step 5: Verify the Controller is healthy

# Check that both containers are running
docker compose ps

# Hit the health endpoint
curl -s http://localhost:3000/health | jq

# Expected output:
# {"status": "ok"}

Code Examples

Common installation and verification commands collected in one place for quick reference.

macOS: Remove Gatekeeper quarantine attribute

xattr -cr /Applications/NetStacks.app

Linux: Run the AppImage

chmod +x NetStacks-*.AppImage && ./NetStacks-*.AppImage

Generate a secure VAULT_MASTER_KEY

openssl rand -hex 32

Generate a secure JWT_SECRET

openssl rand -base64 48

Start Controller with a full rebuild

docker compose up -d --build

Check Controller health

curl -s http://localhost:3000/health | jq

Tail Controller API logs

docker compose logs -f api

Update Controller to latest version

docker compose pull && docker compose up -d

Q&A

How do I install NetStacks on macOS?

Download the DMG for your architecture (aarch64 for Apple Silicon, x64 for Intel) from the downloads page. Open the DMG, drag NetStacks.app to Applications, and right-click the app on first launch to bypass Gatekeeper. See the macOS installation section for details.

How do I deploy the Controller?

The Controller runs as a Docker Compose stack. Create a project directory, add a docker-compose.yml and a .env file with secure secrets, then run docker compose up -d. Full instructions are in the Controller section.

What Docker version is required for the Controller?

Docker Engine 20.10 or later with Docker Compose v2 (the docker compose subcommand). The legacy standalone docker-compose binary is not supported because the Compose file uses v2 syntax features.

How do I update NetStacks Terminal?

Terminal includes a built-in auto-updater. When a new version is available, you will see an update prompt inside the application. Click Update Now to download and install the new version without leaving the app. No manual download is required.

How do I update the Controller?

Pull the latest container images and restart the stack:
docker compose pull && docker compose up -d
Your data is persisted in Docker volumes and survives container restarts.

Can I run the Controller without Docker?

Docker is the only officially supported deployment method. The Controller API is a standalone Rust binary, so advanced users can compile and run it directly, but you will need to provision PostgreSQL 16 with pgvector yourself and set all environment variables manually. This configuration is not documented or supported.

What ports does the Controller use?

By default, the API server listens on port 3000 and PostgreSQL listens on port 5432. Both are configurable via the .env file. If either port is already in use on your host, change the port mapping in docker-compose.yml.

Troubleshooting

macOS: "NetStacks.app is damaged and can't be opened"

This Gatekeeper error appears when the quarantine attribute is set on the downloaded DMG. Remove it by running:

xattr -cr /Applications/NetStacks.app

Windows: SmartScreen blocks the installer

Because the binary is code-signed but not yet widely distributed, SmartScreen may flag the first run. Click More info, then click Run anyway.

Linux: Missing libwebkit2gtk or libfuse2

The AppImage requires libfuse2 and the Tauri webview requires libwebkit2gtk-4.1. Install both on Ubuntu 22.04+:

sudo apt install libwebkit2gtk-4.1-0 libfuse2

Docker Compose: "version" key warning or v1 syntax errors

The NetStacks docker-compose.yml uses Compose v2 syntax (no top-level version: key). If you see errors about missing version, make sure you are running Docker Compose v2 via docker compose (not the legacy docker-compose standalone binary).

# Verify you have Compose v2
docker compose version
# Expected: Docker Compose version v2.x.x

Port 3000 or 5432 already in use

If another service is using port 3000 or 5432, either stop the conflicting service or change the host-side port mapping in docker-compose.yml. For example, to move the API to port 3001:

# In docker-compose.yml, under api > ports:
ports:
  - "3001:3000"

PostgreSQL container won't start

Common causes: insufficient disk space for the data volume, or a previous volume with incompatible data. Check disk space with df -h and inspect the database logs with docker compose logs db. To start fresh, remove the volume:

docker compose down -v  # WARNING: deletes all data
docker compose up -d

Related Features

Now that NetStacks is installed, continue with these guides:

• Introduction -- learn what NetStacks is and how the Terminal and Controller work together
• System Requirements -- full hardware and software requirements for all platforms
• Quick Start Guide -- connect to your first network device in under five minutes
• Terminal Overview -- deep dive into the Terminal interface, tabs, split panes, and keyboard shortcuts