NetStacksNetStacks
Get Started

Installation

Step-by-step instructions for installing NetStacks on your platform.

Terminal Installation

The NetStacks Terminal is a native desktop application available for macOS, Windows, and Linux. Download the appropriate installer for your platform from the downloads page.

macOS

NetStacks supports both Intel and Apple Silicon Macs. Download the appropriate DMG for your processor:

  • Apple Silicon (M1/M2/M3) - NetStacks-arm64.dmg (45 MB)
  • Intel - NetStacks-x64.dmg (48 MB)

Installation Steps

  1. Download the appropriate DMG file
  2. Open the DMG file
  3. Drag NetStacks.app to your Applications folder
  4. Launch NetStacks from Applications or Spotlight
Gatekeeper Warning

On first launch, you may see a security warning. Right-click the app and select "Open" to bypass Gatekeeper, or go to System Preferences → Security & Privacy to allow the app.

Windows

Two installation options are available for Windows:

  • MSI Installer - NetStacks-Setup.msi (52 MB) - Recommended for most users
  • Portable ZIP - NetStacks-Portable.zip (50 MB) - No installation required

MSI Installation Steps

  1. Download NetStacks-Setup.msi
  2. Double-click to run the installer
  3. Follow the installation wizard
  4. Launch NetStacks from the Start Menu

Portable Installation

  1. Download NetStacks-Portable.zip
  2. Extract to your preferred location
  3. Run NetStacks.exe
Windows Defender

Windows Defender SmartScreen may block the first run. Click "More info" then "Run anyway" to proceed.

Linux

NetStacks is available in multiple formats for Linux:

  • AppImage - NetStacks.AppImage (55 MB) - Universal, no installation
  • DEB Package - netstacks.deb (48 MB) - Debian/Ubuntu
  • RPM Package - netstacks.rpm (48 MB) - Fedora/RHEL/CentOS

AppImage Installation

chmod +x NetStacks.AppImage
./NetStacks.AppImage

Debian/Ubuntu Installation

sudo dpkg -i netstacks.deb
sudo apt-get install -f  # Install dependencies if needed

Fedora/RHEL Installation

sudo rpm -i netstacks.rpm
# Or with DNF:
sudo dnf install netstacks.rpm

Controller Installation

The NetStacks Controller is a server-side component for enterprise deployments. It provides centralized device management, credential storage, and automation capabilities.

Note

The Controller is optional for standalone Terminal use. Install it only if you need centralized management for your team.

Docker Compose

The recommended way to deploy the Controller is using Docker Compose:

Prerequisites

  • Docker Engine 20.10+
  • Docker Compose v2.0+
  • 2 GB RAM minimum (4 GB recommended)
  • 10 GB disk space

Installation Steps

terminalbash
# Clone the repository
git clone https://github.com/netstacks/netstacks.git
cd netstacks/controller

# Copy and configure environment variables
cp .env.example .env

# Edit .env with your settings
# IMPORTANT: Set a strong VAULT_MASTER_KEY
nano .env

# Start the services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f netstacks-api

Required Environment Variables

.envbash
# Database connection
DATABASE_URL=postgresql://netstacks:password@postgres:5432/netstacks

# REQUIRED: Master key for credential encryption
# Generate with: openssl rand -base64 32
VAULT_MASTER_KEY=your-secure-master-key-here

# Server configuration
HOST=0.0.0.0
PORT=3000
BASE_URL=https://controller.yourdomain.com

# SSH Proxy (optional)
SSH_PROXY_ENABLED=true
SSH_PROXY_ADDR=0.0.0.0:2222
Secure Your Master Key

The VAULT_MASTER_KEY is used to encrypt all credentials. Store it securely and back it up. If lost, encrypted credentials cannot be recovered.

Verifying Installation

Terminal Verification

Launch the Terminal application and verify you can create a local shell session:

  1. Open NetStacks Terminal
  2. A local shell tab should open automatically
  3. Run a command like echo "Hello NetStacks"

Controller Verification

Verify the Controller is running correctly:

# Check health endpoint
curl http://localhost:3000/health

# Expected response:
# {"status":"healthy","version":"1.0.0"}

# Access the Admin UI
# Open http://localhost:3000 in your browser
Tip

Default admin credentials are created on first startup. Check the logs for the initial password, or set ADMIN_PASSWORD in your environment.