Documentation > Server > Installation

Server Installation Guide

Complete step-by-step installation guide for setting up the SysManage server on your infrastructure.

System Requirements

🐍 Python

Required: 3.11 or 3.12

Note: Python 3.13 is NOT yet supported due to package compatibility issues

🟢 Node.js

Required: 20.x or higher

For building the React frontend

🐘 PostgreSQL

Required: 14 or higher

Primary database for all application data

💻 Operating System

Supported: Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD

Cross-platform deployment

Platform-Specific Prerequisites

Ubuntu 22.04 - 24.10 (Recommended)

# Update package manager
sudo apt update

# Install Python 3.11 or 3.12 (AVOID 3.13)
sudo apt install python3.11 python3.11-venv python3.11-dev python3-pip

# For Python 3.12 (if available):
# sudo add-apt-repository ppa:deadsnakes/ppa
# sudo apt update
# sudo apt install python3.12 python3.12-venv python3.12-dev python3-pip

# Install Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Install PostgreSQL 14+
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Install build tools and development libraries
sudo apt install build-essential libffi-dev libssl-dev libpq-dev
sudo apt install libuv1-dev python3-setuptools

Ubuntu 25.04+ (Python 3.12 from Source)

Note: Ubuntu 25.04+ only ships with Python 3.13, which is not yet compatible. You must build Python 3.12 from source:

# Install build dependencies
sudo apt install build-essential libssl-dev zlib1g-dev libbz2-dev \
    libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev \
    libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev \
    python3-openssl git libpq-dev libuv1-dev

# Download and build Python 3.12
cd /tmp
wget https://www.python.org/ftp/python/3.12.7/Python-3.12.7.tgz
tar -xf Python-3.12.7.tgz
cd Python-3.12.7

# Configure and build (takes 10-15 minutes)
./configure --enable-optimizations --with-ensurepip=install
make -j$(nproc)
sudo make altinstall

# Verify installation
python3.12 --version

# Install remaining packages
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

CentOS/RHEL/Fedora

# Install Python 3.12+
sudo dnf install python3 python3-devel python3-pip

# Install Node.js 20.x
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs

# Install PostgreSQL 14+
sudo dnf install postgresql postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Install build tools and libraries
sudo dnf groupinstall "Development Tools"
sudo dnf install libffi-devel openssl-devel postgresql-devel
sudo dnf install libuv-devel python3-setuptools

# Configure firewall to allow SysManage ports
sudo firewall-cmd --permanent --add-port=8080/tcp  # Backend API
sudo firewall-cmd --permanent --add-port=3000/tcp  # Frontend UI
sudo firewall-cmd --reload

macOS

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python 3.12
brew install python@3.12

# Install Node.js 20.x
brew install node@20
brew link node@20

# Install PostgreSQL 14+
brew install postgresql@14
brew services start postgresql@14

# Install Xcode Command Line Tools
xcode-select --install

Windows

  1. Python 3.12: Download from python.org
    • ⚠️ AVOID Python 3.13 - Limited Windows binary support
    • ✅ Check "Add Python to PATH" during installation
  2. Node.js 20.x: Download from nodejs.org
  3. PostgreSQL 14+: Download from postgresql.org
  4. Git for Windows: Download from git-scm.com
  5. Visual Studio Build Tools: Download from Microsoft

FreeBSD

# Update package manager
sudo pkg update

# Install Python 3.12+
sudo pkg install python312 py312-pip py312-sqlite3

# Install Node.js 20.x
sudo pkg install node20 npm

# Install PostgreSQL 14+
sudo pkg install postgresql14-server postgresql14-client
sudo service postgresql enable
sudo service postgresql initdb
sudo service postgresql start

# Install Go (required for OpenBAO)
sudo pkg install go

# Install build tools
sudo pkg install gcc cmake make

OpenBSD

# Update package manager
doas pkg_add -u

# Install Python 3.12+
doas pkg_add python-3.12 py3-pip

# Install Node.js 20.x
doas pkg_add node

# Install PostgreSQL 14+
doas pkg_add postgresql-server postgresql-client
doas rcctl enable postgresql
doas su - _postgresql -c "initdb -D /var/postgresql/data"
doas rcctl start postgresql

# Install build tools (required for cryptography packages)
doas pkg_add rust gcc cmake gmake pkgconf

# Install additional tools for telemetry and gRPC compilation
# Note: These are required for building grpcio and OpenTelemetry from source
doas pkg_add gcc-11.2.0p15 findutils coreutils grpc

# IMPORTANT: OpenBSD requires building some Python packages from source
# The SysManage build system will automatically handle this during 'make install-dev'
# This includes: grpcio, cffi, and all OpenTelemetry packages

NetBSD Complete Setup Guide

# ===== QUICK INSTALL: All packages in one command =====
# Required + Optional packages for full development environment:
pkgin install python312 py312-pip py312-sqlite3 nodejs npm \
    postgresql14-server postgresql14-client gcc13 cmake gmake pkgconf \
    rust py312-cffi jpeg libjpeg-turbo tiff png freetype2 lcms2 \
    libwebp openjpeg zlib findutils coreutils go git chromium firefox

# ===== OR STEP BY STEP INSTALLATION =====
# ===== STEP 1: Update package manager =====
pkgin update

# ===== STEP 2: Install all required packages =====
# Install Python 3.12
pkgin install python312 py312-pip py312-sqlite3

# Install Node.js and npm
pkgin install nodejs npm

# Install PostgreSQL 14+
pkgin install postgresql14-server postgresql14-client

# Install ALL required build tools and libraries:
# IMPORTANT: jpeg package is required in addition to libjpeg-turbo!
pkgin install gcc13 cmake gmake pkgconf rust py312-cffi \
    jpeg libjpeg-turbo tiff png freetype2 lcms2 libwebp openjpeg zlib

# Install GNU utilities (REQUIRED for OpenTelemetry Collector build from source)
# Provides: gfind, gxargs (findutils) and gdirname (coreutils)
pkgin install findutils coreutils

# Optional: Install Go if you want to build OpenBAO or OpenTelemetry from source
# (Both are optional - the system works without them)
pkgin install go git  # Only needed if you want OpenBAO or OTEL Collector

# NetBSD installs Go as go124 - create a symlink for compatibility:
sudo ln -sf /usr/pkg/bin/go124 /usr/pkg/bin/go

# Install browsers for UI testing and screenshots
pkgin install chromium firefox  # Needed for browser automation tests

# ===== STEP 3: Set environment variables (CRITICAL for NetBSD) =====
# NetBSD installs packages in /usr/pkg, not standard locations
# These MUST be set before installing Python packages with C extensions

# Set for current session:
export CFLAGS="-I/usr/pkg/include"
export LDFLAGS="-L/usr/pkg/lib -Wl,-R/usr/pkg/lib"

# Make permanent (add to ~/.profile for sh/ksh or ~/.bashrc for bash):
echo 'export CFLAGS="-I/usr/pkg/include"' >> ~/.profile
echo 'export LDFLAGS="-L/usr/pkg/lib -Wl,-R/usr/pkg/lib"' >> ~/.profile

# Source the profile to apply changes:
. ~/.profile

# ===== STEP 4: Set up PATH for local binaries =====
# Add ~/.local/bin to PATH (needed for OpenBAO and other local tools)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
. ~/.profile

# PostgreSQL Setup on NetBSD
# IMPORTANT: NetBSD may not have the pgsql user created automatically

# Create the postgres user and group (if not already present)
sudo useradd -m -d /var/db/postgresql -s /bin/sh postgres
sudo groupadd postgres   # only if group not auto-created

# Set ownership of the database directory
sudo mkdir -p /var/db/postgresql/data
sudo chown -R postgres:postgres /var/db/postgresql

# Initialize the database as postgres user
sudo -u postgres /usr/pkg/bin/initdb -D /var/db/postgresql/data
# Note: Path might be /usr/pkg/postgresql14/bin/initdb - run 'which initdb' to confirm

# Copy rc.d script and configure startup
sudo cp /usr/pkg/share/examples/rc.d/pgsql /etc/rc.d/
sudo chmod 755 /etc/rc.d/pgsql

# Enable PostgreSQL to start at boot
echo 'pgsql=YES' | sudo tee -a /etc/rc.conf

# Start PostgreSQL
sudo /etc/rc.d/pgsql start

# Verify PostgreSQL is running
sudo /etc/rc.d/pgsql status

# IMPORTANT: /tmp filesystem considerations
# NetBSD uses tmpfs for /tmp with a default 1GB limit
# If you encounter "No space left on device" errors during pip installs:
#
# Option 1: Increase /tmp size (as root):
mount -t tmpfs -o -s=4g tmpfs /tmp
#
# Option 2: Make permanent in /etc/fstab:
# tmpfs /tmp tmpfs rw,-s=4g 0 0
#
# Option 3: Use alternate temp directory:
export TMPDIR=$HOME/tmp
mkdir -p $HOME/tmp

openSUSE Leap/Tumbleweed

# Update package manager
sudo zypper refresh

# Install Python 3.11 or 3.12 (AVOID 3.13)
sudo zypper install python311 python311-pip python311-devel

# For Python 3.12 (if available in Tumbleweed):
# sudo zypper install python312 python312-pip python312-devel

# Install Node.js 20.x
sudo zypper install nodejs20 npm20

# Install PostgreSQL 14+
sudo zypper install postgresql14-server postgresql14-contrib
sudo systemctl enable postgresql
sudo systemctl start postgresql

# Install build tools and development libraries
sudo zypper install gcc gcc-c++ make cmake pkg-config
sudo zypper install libopenssl-devel libffi-devel postgresql14-devel
sudo zypper install libuv-devel python311-setuptools

# Configure firewall to allow SysManage ports
sudo firewall-cmd --permanent --add-port=8080/tcp  # Backend API
sudo firewall-cmd --permanent --add-port=3000/tcp  # Frontend UI
sudo firewall-cmd --reload

📦 Package Manager Notes

  • openSUSE Leap: Stable packages, Python 3.11 typically available
  • openSUSE Tumbleweed: Rolling release with latest packages
  • Node.js versions: May need to specify version (nodejs20) explicitly
  • PostgreSQL: Specify version (postgresql14) for compatibility

SUSE Linux Enterprise Server (SLES)

# Update package manager
sudo zypper refresh

# Install Python 3.11 or 3.12 and development tools
sudo zypper install python311 python311-pip python311-devel
sudo zypper install gcc gcc-c++ make cmake pkg-config

# Install Node.js 20.x (may require additional repository)
# For SLES 15 SP4+:
sudo SUSEConnect -p sle-module-web-scripting/15.4/x86_64
sudo zypper install nodejs20 npm20

# Install PostgreSQL 14+
sudo zypper install postgresql14-server postgresql14-contrib postgresql14-devel
sudo systemctl enable postgresql
sudo systemctl start postgresql

# Install development libraries
sudo zypper install libopenssl-devel libffi-devel libpq5
sudo zypper install libuv-devel python311-setuptools

# For SLES 15 SP4+, you may also need:
sudo zypper install glibc-devel kernel-devel

# Configure firewall (SuSEfirewall2 or firewalld)
sudo firewall-cmd --permanent --add-port=8080/tcp  # Backend API
sudo firewall-cmd --permanent --add-port=3000/tcp  # Frontend UI
sudo firewall-cmd --reload

🏢 Enterprise Considerations

  • SLES 12: May require Software Collections (SCL) for newer Python
  • SLES 15: Python 3.6+ included, but 3.11+ recommended
  • Modules: Some packages require enabling additional modules via SUSEConnect
  • Firewall: May use SuSEfirewall2 (older) or firewalld (newer)
  • SELinux: May require policy adjustments if enabled
  • Subscription: Active SLES subscription required for full package access

Installation Steps

⚠️ NetBSD Users - Critical Setup Requirements

Before starting installation, NetBSD users MUST:

  1. Install ALL required packages including jpeg (not just libjpeg-turbo)
  2. Set environment variables: export CFLAGS="-I/usr/pkg/include" LDFLAGS="-L/usr/pkg/lib -Wl,-R/usr/pkg/lib"
  3. Use gmake instead of make for all make commands
  4. Manually create PostgreSQL user if not present
  5. Increase /tmp size if needed: mount -t tmpfs -o -s=4g tmpfs /tmp

See the NetBSD tab in Prerequisites above for complete setup instructions.

Step 1: Clone and Setup

git clone https://github.com/bceverly/sysmanage.git
cd sysmanage

# NetBSD ONLY: Set environment variables BEFORE creating venv
# (Required for building Python packages with C extensions)
export CFLAGS="-I/usr/pkg/include"
export LDFLAGS="-L/usr/pkg/lib -Wl,-R/usr/pkg/lib"

# Create Python virtual environment (use specific version)
python3.11 -m venv .venv  # Or python3.12 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
                           # FreeBSD/OpenBSD/NetBSD: . .venv/bin/activate

# Upgrade pip to latest version
pip install --upgrade pip

Step 2: Database Setup

Create PostgreSQL database and user:

# Switch to postgres user
sudo su - postgres

# Start psql
psql

# In PostgreSQL prompt (using dev credentials):
CREATE USER sysmanage WITH PASSWORD 'abc123';
CREATE DATABASE sysmanage OWNER sysmanage;
GRANT ALL PRIVILEGES ON DATABASE sysmanage TO sysmanage;

# Grant schema permissions
\c sysmanage
GRANT ALL ON SCHEMA public TO sysmanage;

# Exit PostgreSQL
\q
# Switch to _postgresql user
doas -u _postgresql psql postgres

# Run the same SQL commands as Linux/macOS
CREATE USER sysmanage WITH PASSWORD 'abc123';
CREATE DATABASE sysmanage OWNER sysmanage;
GRANT ALL PRIVILEGES ON DATABASE sysmanage TO sysmanage;
\c sysmanage
GRANT ALL ON SCHEMA public TO sysmanage;
\q
# Note: PostgreSQL on NetBSD often uses TCP/IP connections
# Connect as the postgres user (created during setup above)
sudo su - postgres
psql -h localhost postgres

# Alternative: If using pgsql user instead of postgres:
psql -h localhost -U pgsql postgres

# Run the same SQL commands as Linux/macOS
CREATE USER sysmanage WITH PASSWORD 'abc123';
CREATE DATABASE sysmanage OWNER sysmanage;
GRANT ALL PRIVILEGES ON DATABASE sysmanage TO sysmanage;
\c sysmanage
GRANT ALL ON SCHEMA public TO sysmanage;
\q

# Test the connection with the new user:
PGPASSWORD=abc123 psql -h localhost -U sysmanage -d sysmanage -c "SELECT version();"
# Open "SQL Shell (psql)" from Start Menu
# Or use Command Prompt:
psql -U postgres -h localhost

# Run the same SQL commands:
CREATE USER sysmanage WITH PASSWORD 'abc123';
CREATE DATABASE sysmanage OWNER sysmanage;
GRANT ALL PRIVILEGES ON DATABASE sysmanage TO sysmanage;
\c sysmanage
GRANT ALL ON SCHEMA public TO sysmanage;
\q

⚠️ Security Notes

  • Development password abc123 matches sysmanage-dev.yaml
  • NEVER use this password in production
  • Change password in both PostgreSQL AND your configuration file

Step 3: Install Backend Dependencies

pip install -r requirements.txt

# For development installation with testing tools:
# Linux/macOS: make install-dev
# BSD systems: gmake install-dev

Step 4: Test Database Connection

# Test connection with development credentials
PGPASSWORD=abc123 psql -U sysmanage -d sysmanage -h localhost -c "SELECT version();"

Step 5: Install Frontend Dependencies

cd frontend
npm install

Step 6: Configuration

Create configuration file at:

💡 Configuration Generator Available

Use the interactive Configuration Builder Tool to generate customized configuration files for your environment.

  • Linux/macOS/FreeBSD/OpenBSD/NetBSD: /etc/sysmanage.yaml
  • Windows: C:\ProgramData\SysManage\sysmanage.yaml
api:
  host: "localhost"
  port: 8080

database:
  user: "sysmanage"
  password: "abc123"  # CHANGE FOR PRODUCTION!
  host: "localhost"
  port: 5432
  name: "sysmanage"

security:
  password_salt: "GENERATE_NEW_BASE64_STRING"
  admin_userid: "admin@yourdomain.com"
  admin_password: "CHANGE_THIS_PASSWORD"
  jwt_secret: "GENERATE_NEW_JWT_SECRET"
  jwt_algorithm: "HS256"
  jwt_auth_timeout: 6000
  jwt_refresh_timeout: 60000

webui:
  host: "localhost"
  port: 3000

🔐 Required Security Steps

  1. Generate new secrets: openssl rand -base64 32
  2. Use strong passwords (12+ characters)
  3. Set proper file permissions: chmod 600 /etc/sysmanage.yaml
  4. Never commit configuration files to version control

Step 7: Run Secure Installation Script

🔐 REQUIRED for New Installations

The secure installation script must be run to create the initial admin user and configure unique security tokens for your installation.

# Run the secure installation script
scripts/sysmanage_secure_installation

What this script does:

  • Creates the initial administrative user account
  • Generates unique JWT secret for authentication
  • Generates unique password salt for secure password hashing
  • Applies security hardening to configuration files
  • Prevents use of default/example security tokens

⚠️ Important Security Notes

  • This step is REQUIRED - the application will not function securely without it
  • Each installation gets unique security tokens to prevent credential reuse
  • Only run this script once per installation
  • Backup your configuration file after running this script

Step 8: Start the Application

# Start backend API server
uvicorn backend.main:app --reload --host 0.0.0.0 --port 6443

# In another terminal, start frontend (development)
cd frontend
npm run dev

Access the application at:

  • HTTPS: https://sysmanage.org:7443 (if SSL certs exist)
  • HTTP: http://localhost:3000 (fallback)

SSL Certificates (Optional)

For HTTPS development, place your SSL certificates in:

~/dev/certs/sysmanage.org/
├── cert.pem
└── privkey.pem

If certificates are not found, the system automatically falls back to HTTP on localhost.

Troubleshooting

Package Build Errors

  • Missing libpq-fe.h: Install libpq-dev (Ubuntu) or postgresql-devel (RHEL)
  • httptools build errors: Install libuv1-dev (Ubuntu) or libuv-devel (RHEL)
  • Python 3.13 issues: Use Python 3.11 or 3.12 instead

Database Connection Issues

  • Verify PostgreSQL is running: sudo systemctl status postgresql
  • Check credentials match configuration file
  • Test connection with psql command shown above

Port Conflicts

  • Ensure ports 6443 (API) and 7443 (frontend) are available
  • Check for existing services: netstat -tlnp | grep :6443
  • Modify ports in configuration if needed

Permission Issues

  • Set configuration file permissions: chmod 600 /etc/sysmanage.yaml
  • Ensure proper ownership of directories
  • Check virtual environment activation

NetBSD-Specific Issues

  • PostgreSQL user missing: NetBSD may not create the postgres/pgsql user automatically. Create it with: sudo useradd -m -d /var/db/postgresql -s /bin/sh postgres
  • PostgreSQL won't start: Ensure pgsql=YES is in /etc/rc.conf, then run sudo /etc/rc.d/pgsql start
  • No space left on device during pip install: NetBSD's /tmp is limited to 1GB by default. Increase with: mount -t tmpfs -o -s=4g tmpfs /tmp or use export TMPDIR=$HOME/tmp
  • gmake install-dev for development: Use gmake instead of make. The Makefile includes NetBSD-specific C tracer dependency checks (gcc13, py312-cffi)
  • PostgreSQL socket not found: NetBSD PostgreSQL often uses TCP instead of Unix sockets. Always use -h localhost when connecting
  • OpenTelemetry Collector build failures: NetBSD uses BSD versions of find/xargs/dirname which are incompatible with the OTEL Collector Makefile. Install GNU utilities: 
    sudo pkgin install findutils coreutils
    The install-telemetry.py script will automatically detect and use gfind/gxargs/gdirname on NetBSD.
  • Browser/WebDriver errors: Install browsers for UI testing: 
    # Install Chromium (includes ChromeDriver)
doas pkgin install chromium

# Install Firefox (requires version-specific name)
doas pkgin install firefox-138.0.4

# Install GeckoDriver for Firefox UI testing
doas pkgin install geckodriver-0.36.0

# Verify installations
which chromium firefox geckodriver
    Note: NetBSD Firefox packages often require explicit version numbers unlike other BSD systems. Due to Firefox WebDriver compatibility issues on NetBSD, the UI test suite automatically excludes Firefox tests and runs Chrome-only tests. This ensures clean test results without failures or skipped tests.
  • Pillow build failures: Install image libraries and set paths: 
    pkgin install jpeg libjpeg-turbo tiff png freetype2 lcms2 libwebp openjpeg zlib
export CFLAGS="-I/usr/pkg/include"
export LDFLAGS="-L/usr/pkg/lib -Wl,-R/usr/pkg/lib"
  • Backend fails to start with "libjpeg.so.9 not found": This occurs when Pillow was installed before the JPEG library or with incorrect paths. The gmake install-dev target automatically rebuilds Pillow for NetBSD. For manual fix: 
    . .venv/bin/activate
export CFLAGS="-I/usr/pkg/include"
export LDFLAGS="-L/usr/pkg/lib -Wl,-R/usr/pkg/lib"
pip uninstall -y Pillow
pip install --no-binary=:all: Pillow
  • OpenBAO installation: NetBSD doesn't have pre-built OpenBAO packages. Options:
    1. Build from source (recommended): 
      pkgin install go git gmake
# NetBSD installs Go as go124 - create symlink:
sudo ln -sf /usr/pkg/bin/go124 /usr/pkg/bin/go
# Add ~/.local/bin to PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
. ~/.profile
# Then run: gmake install-dev
# It will prompt to build OpenBAO from source
    2. Use Linux emulation: Try running Linux binaries under NetBSD's Linux compatibility
    3. Skip OpenBAO: It's optional - set vault.enabled=false in config
    Note: OpenBAO is optional for development. The system works perfectly without it.
  • OpenBAO 'bao' command not found: Ensure ~/.local/bin is in your PATH: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile && . ~/.profile
← Server Documentation Configuration Guide →