Nexus-Guard-Suite/docs/portfolio/deployment.md

Deployment Guide

NexusGuard supports three deployment modes: Docker (recommended), native install, and development.

Docker Deployment (Recommended)

Prerequisites

• Docker 20.10+
• Docker Compose v2
• Git

Quick Start

# Clone repository
git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite

# Start all services (auto-generates .env on first run)
bash update.sh

First Boot

On first run, the system automatically:

1. Pulls latest code and builds Docker containers
2. Generates Local Primary Node WireGuard keys
3. Creates database schema via migration

Configuration

Edit .env in root directory:

# Database
DB_HOST=postgres
DB_PORT=5432
DB_USER=nexusguard
DB_PASSWORD=your_secure_password
DB_NAME=nexusguard

# Redis
REDIS_ADDR=redis:6379

# Security (auto-generated by update.sh)
JWT_SECRET=<hex-64-chars>
SERVER_SALT=<hex-64-chars>

# Network
NFTABLES_TABLE=nexusguard
IPAM_POOL=10.8.0.0/16

# Server
GIN_MODE=release
PORT=8080

# Dashboard
VITE_API_BASE_URL=https://api.yourdomain.com/api/v1

Update Commands

bash update.sh              # Smart update (rebuild only if changes)
bash update.sh --force      # Force rebuild
bash update.sh --backup     # Backup PostgreSQL before update
bash update.sh --no-migrate # Skip database migration

Makefile Commands

Command	Description
make up	Start all services
make down	Stop all services
make logs	Tail all service logs
make dev	Start with hot-reload
make migrate	Run database migration
make reset-db	Reset database to initial state

Create Admin Account

docker exec -it nexus-guard-suite-server-core-1 ./server-core \
  -create-admin -user admin -pass "YourSecurePassword123!"

Service Architecture

┌─────────────────────────────────────────────────┐
│                  Docker Compose                  │
│                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐ │
│  │ nginx    │  │ server-  │  │ postgres     │ │
│  │ :80/:443 │→ │ core     │→ │ :5432        │ │
│  │          │  │ :8080    │  │              │ │
│  └──────────┘  └──────────┘  └──────────────┘ │
│       ↑              ↑                         │
│  ┌──────────┐  ┌──────────┐                   │
│  │ dashboard│  │ redis    │                   │
│  │ (static) │  │ :6379    │                   │
│  └──────────┘  └──────────┘                   │
└─────────────────────────────────────────────────┘

Port Mapping

Service	Container Port	Host Port
nginx	80	80
nginx	443	443
server-core	8080	8080
postgres	5432	5432
redis	6379	6379

Volumes

Volume	Purpose
postgres_data	PostgreSQL data persistence
redis_data	Redis data persistence

---

Native Install

For production servers without Docker.

Prerequisites

Debian/Ubuntu:

sudo apt install -y golang nginx postgresql redis-server nftables wireguard-tools

CentOS/Rocky:

sudo dnf install -y golang nginx postgresql-server redis nftables wireguard-tools

Build Binaries

Server Core:

cd apps/server-core
CGO_ENABLED=0 go build -o ../../bin/server-core .
cd ../..

Dashboard UI:

cd apps/dashboard-ui
npm install
VITE_API_BASE_URL=/api/v1 npm run build
cd ../..

Run Installer

sudo bash nexusguard-install.sh

Options:

sudo bash nexusguard-install.sh --server-port 8080 --web-port 80
sudo bash nexusguard-install.sh --db-host 127.0.0.1 --db-pass mypassword

What the installer does:

1. Creates PostgreSQL database and user
2. Installs binary to /usr/local/bin/nexusguard-server
3. Installs dashboard to /usr/share/nexusguard/dashboard/
4. Creates config at /etc/nexusguard/nexusguard.conf
5. Runs database migration
6. Creates systemd service
7. Configures nginx

Create Admin Account

sudo /usr/local/bin/nexusguard-server \
  -create-admin -user admin -pass "YourSecurePassword123!"

Service Management

# Start
sudo systemctl start nexusguard-server

# Stop
sudo systemctl stop nexusguard-server

# Status
sudo systemctl status nexusguard-server

# Logs
sudo journalctl -u nexusguard-server -f

Configuration

Edit /etc/nexusguard/nexusguard.conf:

# Database
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=nexusguard
DB_PASSWORD=nexusguard
DB_NAME=nexusguard

# Redis
REDIS_ADDR=127.0.0.1:6379

# Security (auto-generated)
JWT_SECRET=<hex-64-chars>
SERVER_SALT=<hex-64-chars>

# Network
NFTABLES_TABLE=nexusguard
IPAM_POOL=10.8.0.0/16

# Server
GIN_MODE=release
PORT=8080

Uninstall

# Remove files only
sudo bash nexusguard-uninstall.sh

# Also drop database
sudo bash nexusguard-uninstall.sh --remove-db

---

Development Mode

For local development with hot-reload.

Prerequisites

• Go 1.25+
• Node.js 24+
• PostgreSQL
• Redis

Setup Database

1. Create PostgreSQL database:

CREATE DATABASE nexusguard;
CREATE USER nexusguard WITH PASSWORD 'nexusguard';
GRANT ALL PRIVILEGES ON DATABASE nexusguard TO nexusguard;

2. Copy environment template:

cp .env.example .env

3. Edit .env with your database credentials.

Start Backend

cd apps/server-core
go mod download
go run -tags dev .

The -tags dev flag:

• Runs AutoMigrate on startup
• Provisions local node
• Enables debug logging

Start Frontend

cd apps/dashboard-ui
npm install
npm run dev

Dashboard available at http://localhost:5173.

Create Admin Account

cd apps/server-core
go run -tags dev . -create-admin -user admin -pass "YourNewSecurePassword123!"

Development Workflow

┌─────────────────────────────────────────────────────────┐
│                    Development Setup                     │
│                                                         │
│  Terminal 1: Backend                                    │
│  ┌───────────────────────────────────────────────────┐ │
│  │ $ go run -tags dev .                              │ │
│  │ [dev] AutoMigrate complete                        │ │
│  │ [dev] Local node provisioned                      │ │
│  │ [gin] Listening on :8080                          │ │
│  └───────────────────────────────────────────────────┘ │
│                                                         │
│  Terminal 2: Frontend                                   │
│  ┌───────────────────────────────────────────────────┐ │
│  │ $ npm run dev                                     │ │
│  │                                                   │ │
│  │   VITE v8.0.0  ready in 300 ms                    │ │
│  │                                                   │ │
│  │   ➜  Local:   http://localhost:5173/              │ │
│  └───────────────────────────────────────────────────┘ │
│                                                         │
│  Browser: http://localhost:5173                         │
│  → Dashboard UI (Vue 3 + Vite)                         │
│  → API calls proxied to :8080                          │
└─────────────────────────────────────────────────────────┘

---

Agent Installation

Linux (Automated)

# Transfer script
scp scripts/install_agent.sh user@target-machine:~

# Run installer
sudo ./install_agent.sh \
  --server-url "https://api.yourdomain.com" \
  --token "REG_TOKEN_FROM_DASHBOARD"

# Verify
sudo systemctl status sys-bridge.service

Options:

• --binary-name "my-agent" — Override default binary name

What the script does:

1. Detects OS (APT/YUM)
2. Installs dependencies (iproute2, curl)
3. Downloads correct binary for architecture
4. Creates config at ~/.config/nexusguard/nexusguard.conf
5. Creates systemd service
6. Starts agent

Linux (Manual)

# Download binary
sudo cp nexusguard-device-agent-linux-amd64 /usr/local/bin/sys-bridge
sudo chmod +x /usr/local/bin/sys-bridge

# Create config
mkdir -p ~/.config/nexusguard
cat > ~/.config/nexusguard/nexusguard.conf <<EOF
SERVER_URL=https://api.yourdomain.com
REG_TOKEN=YOUR_REG_TOKEN
EOF

# Create systemd service
sudo tee /etc/systemd/system/sys-bridge.service > /dev/null <<EOF
[Unit]
Description=NexusGuard Device Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/sys-bridge
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# Start
sudo systemctl daemon-reload
sudo systemctl enable --now sys-bridge.service

Windows

1. Build GUI binary:

CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build \
  -ldflags="-s -w -H windowsgui" \
  -o nexusguard-device-agent-gui.exe .

2. Place wintun.dll next to executable

3. Run agent — config auto-created at %ProgramData%\NexusGuard\nexusguard.conf

4. Edit config with SERVER_URL and REG_TOKEN

5. Right-click tray icon → Connect

Service Management:

• Install as Service — Register Windows service
• Uninstall Service — Remove Windows service
• Start on Boot — Toggle auto-start

Docker

docker build -t nexus-device-agent .
docker run -d \
  --name nexus-agent \
  --restart unless-stopped \
  --network host \
  --cap-add NET_ADMIN \
  --cap-add NET_RAW \
  -e SERVER_URL=https://api.yourdomain.com \
  -e REG_TOKEN=YOUR_REG_TOKEN \
  nexus-device-agent

Required capabilities:

• NET_ADMIN — Network interface configuration
• NET_RAW — Raw socket access (WireGuard)

---

Troubleshooting

Common Issues

Issue	Cause	Solution
Agent fails to start	Missing config	Check config file has SERVER_URL + REG_TOKEN
Provisioning fails	Invalid token	Generate new token from Dashboard
Tunnel won't create	Missing kernel module	sudo modprobe wireguard
ip addr add fails	Permissions	Run as root or grant CAP_NET_ADMIN
Heartbeat timeout	Network issue	curl -I <SERVER_URL>

Log Locations

Platform	Location
Docker	docker logs -f nexus-guard-suite-server-core-1
Native	sudo journalctl -u nexusguard-server -f
Agent (Linux)	~/.local/share/nexusguard/logs/
Agent (Windows)	%ProgramData%\NexusGuard\logs\
Agent (macOS)	~/Library/Logs/NexusGuard/

Debug Commands

# Check WireGuard interface
sudo wg show

# Test server connectivity
curl -I https://api.yourdomain.com/api/health

# Check agent version
/usr/local/bin/sys-bridge -version

# Run agent in foreground
sudo /usr/local/bin/sys-bridge -debug