Nexus-Guard-Suite/README.md

NexusGuard SD-WAN Suite

NexusGuard is an Enterprise Zero-Trust SD-WAN solution built with Go, Vue 3, and WireGuard. It enables stealth VPN tunneling, centralized IPAM, and real-time network isolation via nftables.

🏗️ System Architecture

This suite contains four main components:

1. Server Core: The central API and VPN Hub managing database state, token distribution, and Linux firewall isolation.
2. Dashboard UI: The Admin Web GUI for managing Nodes, Users, Devices, and Firewall rules. Features a futuristic glassmorphism design system using Vue 3, Vite, TailwindCSS v4, and HeadlessUI.
3. Device Agent: A stealth background daemon for Linux/Windows/macOS client machines that establishes memory-injected WireGuard tunnels.
4. Device Agent Embedded: ESP32-based WireGuard agent for IoT/edge devices. Runs on FreeRTOS + ESP-IDF with lwIP stack.

---

🚀 Deployment & Installation

Option A: Docker (Recommended)

Clone this repository and start all services:

git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite
./setup.sh                  # Generate .env file automatically
# Edit .env with your configuration
bash update.sh              # Pull, build, migrate, and start

The first run will automatically:

• Pull the latest code and build the Docker containers (via update.sh).
• Auto-generate the Local Primary Node WireGuard keys on the first boot.
• Create the database schema via automated migration.

Update Options:

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

Option B: Native Install (Without Docker)

For production servers without Docker. Requires Go 1.25+, Node.js 24+, PostgreSQL, Redis, nginx.

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

1. Build Binaries

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

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

2. 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

The installer will:

• Create PostgreSQL database and user
• Install binary to /usr/local/bin/nexusguard-server
• Install dashboard to /usr/share/nexusguard/dashboard/
• Create config at /etc/nexusguard/nexusguard.conf
• Run database migration
• Create systemd service
• Configure nginx

3. Create Admin Account

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

4. Uninstall

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

Option C: Native Development (Without Docker)

For local development with hot-reload.

1. Setup Database & Environment Create a PostgreSQL database. Copy .env.example to .env and configure DB_HOST, DB_USER, DB_PASSWORD, and DB_NAME to point to your local database.

2. Start Backend (Server Core)

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

(The dev tag automatically runs migrations and provisions the local node)

3. Start Frontend (Dashboard UI)

cd apps/dashboard-ui
npm install
npm run dev

4. Create Admin Account In a new terminal:

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

Quick Reference with Makefile

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

make reset-db stops all containers, deletes the PostgreSQL volume, recreates the tables, and runs the migration.

Domain & Port Configuration

Docker: Edit .env in root directory. Native: Edit /etc/nexusguard/nexusguard.conf.

Key settings:

• API_PORT / PORT — API server port (default: 8080)
• WEB_PORT — Nginx web port (default: 80)
• VITE_API_BASE_URL — Dashboard API endpoint (Docker only, baked at build time)
• DB_PASSWORD — PostgreSQL password
• JWT_SECRET — 256-bit hex key for JWT signing
• SERVER_SALT — 256-bit hex key for encryption

Creating / Changing the Admin Account

The system operates on a strict Zero-Attack Surface policy. The /auth/register API is locked down. To create the first Admin user (or reset their password):

Docker:

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

Native:

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

Development:

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

---

📖 Operational Workflow

Once the server is running and the Admin account is created, follow this flow:

Managing Nodes

1. Go to the Nodes menu.
2. Click Register Node and fill in:
   • Basic Info: Name, Public Key, Public Endpoint
   • Network Settings: Listen Address, Port, MTU, DNS, IP Pool (CIDR), Interface Address
   • Advanced Overrides: Table (Auto/Off), PreUp/PostDown scripts
   • Peer Defaults: Default DNS, MTU, Keepalive, AllowedIPs for new peers on this node
3. The Interface Address is auto-calculated from the IP Pool CIDR (first usable IP) if left empty.
4. Edit existing nodes to adjust any overrides or peer defaults at any time.

Adding Peers (Devices)

1. Go to the Devices menu.
2. Click + Add Peer.
3. Select the target Node and name the device.
4. Toggle Allow Internet Access for full-tunnel VPN (0.0.0.0/0).
5. After creation, you can:
   • Download the .conf file
   • Show the QR code for mobile apps
   • Copy the config text
   • Generate a Share Link (public, time-limited)
   • Configure Firewall Rules for the peer

Advanced Device Settings

Each device has detailed configuration options in its detail page:

• Allowed IPs: Override the default routing prefix
• DNS / MTU / PersistentKeepalive: Device-level overrides (cascade: device > node defaults > hardcoded defaults)
• Notes: Annotate the device
• Suspend/Unsuspend: Temporarily disable the tunnel without deleting the device

Firewall Rules

Manage per-peer nftables firewall rules directly from the UI:

• Allow/block specific IP ranges and port numbers
• Rules are synced to the server kernel in real-time via nft
• Default SSH access (port 22) is provisioned automatically for new peers

Agent Provisioning (automated device registration)

For automated client deployment with the Device Agent:

1. Create a device from the Devices page.
2. Copy the single-use Registration Token.
3. On the target Linux machine, run:

   sudo ./install_agent.sh --server-url "https://api.yourdomain.com" --token "<REG_TOKEN>"
   

4. The agent will securely provision its WireGuard keys via AES-256-GCM and appear as Online on the Dashboard.

---

📚 Documentation

Documentation is built with VitePress and served at /docs/.

Local Development

cd apps/docs
npm install
npm run docs:dev

Building Docs

cd apps/docs
npm run docs:build

The output is in apps/docs/.vitepress/dist/.

Structure

• apps/docs/ — VitePress root (i18n: Indonesian + English)
• apps/server-core/docs/ — Backend API docs & guides
• apps/dashboard-ui/docs/ — Dashboard UI docs
• apps/device-agent/docs/ — Device Agent docs

Languages

• Bahasa Indonesia (default): /docs/
• English: /docs/en/

---

📁 File Structure

NexusGuard/
├── apps/
│   ├── server-core/        # Go/Gin API backend
│   ├── dashboard-ui/       # Vue 3 frontend
│   └── device-agent/       # Go client agent
├── bin/                    # Built binaries (gitignored)
├── docker-compose.yml      # Docker orchestration
├── docker-compose.dev.yml  # Docker dev (hot-reload)
├── update.sh               # Docker update script
├── setup.sh                # Docker initial setup
├── nexusguard-install.sh   # Native install script
├── nexusguard-uninstall.sh # Native uninstall script
├── .env.example            # Environment template
└── Makefile                # Quick commands