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.

System Architecture

This suite contains three main components:

1. Server Core (Master/Hub) — The central API and VPN Hub managing IPAM, routing, and nftables isolation.
2. Dashboard UI — The Admin web interface for managing users, devices, and firewall rules.
3. Device Agent — A stealth background service for client machines that establishes secure WireGuard tunnels.

┌──────────────────┐     JWT Auth     ┌──────────────────┐
│   Dashboard UI   │ ────────────────▶ │   Server Core    │
│   (Vue 3 / Vite) │ ◀──────────────── │ (Go / Gin/GORM)  │
└──────────────────┘   REST API :8080  └──────┬───────────┘
                                              │
                          AES-256-GCM Config  │  Heartbeat
                          ┌───────────────────┴──────────┐
                          ▼                              ▼
                   ┌──────────────┐             ┌──────────────┐
                   │Device Agent  │◀─ WireGuard ─│Device Agent  │
                   │(stealth WG)  │    tunnel     │(stealth WG)  │
                   └──────────────┘             └──────────────┘

---

Complete Workflow Guide

1. Clone Repository

git clone --recursive http://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite

2. Start Infrastructure (Docker)

cp apps/server-core/.env.example .env
# edit .env — at minimum ganti JWT_SECRET dan SERVER_SALT
docker compose up -d

Ini akan menjalankan:

• PostgreSQL 16 — database utama
• Redis 7 — heartbeat/cache
• Server Core — API server port :8080

3. Create Admin User

Server berjalan di container. Untuk membuat admin user pertama, jalankan:

# Lihat container name
docker compose ps

# Exec ke container server-core
docker compose exec server-core ./server-core -create-admin -user "admin" -pass "PasswordKuat123!"

Atau jika build dari source:

cd apps/server-core
go run . -create-admin -user "admin" -pass "PasswordKuat123!"

Perintah ini membuat user admin dengan password yang sudah di-hash bcrypt di PostgreSQL.

4. Start Dashboard UI

cd apps/dashboard-ui
cp .env.example .env
npm install
npm run dev

Buka http://localhost:5173 dan login dengan user admin yang dibuat di step 3.

5. Create Regular Users

Hanya user bernama admin yang bisa membuat user lain. Setelah login sebagai admin:

1. Buka Dashboard UI
2. Register user baru (fitur register hanya visible untuk admin)

6. Register Device

1. Login ke Dashboard sebagai user biasa
2. Klik "+ New Device", masukkan nama device
3. Copy Registration Token yang muncul
4. Install agent di mesin client:

sudo bash apps/device-agent/scripts/install_agent.sh \
  --server-url "http://<SERVER_IP>:8080" \
  --token "<REGISTRATION_TOKEN>"

5. Device akan muncul sebagai Online di Dashboard.

---

Repository Structure

Nexus-Guard-Suite/
├── apps/
│   ├── server-core/     → http://git.datadunia.com/nexusguard/nexus-server-core
│   ├── device-agent/    → http://git.datadunia.com/nexusguard/nexus-device-agent
│   └── dashboard-ui/    → http://git.datadunia.com/nexusguard/nexus-dashboard-ui
├── docker-compose.yml   → PostgreSQL + Redis + Server Core
├── docker-compose.dev.yml
├── setup.sh             → Start Docker
├── upgrade.sh           → Git pull + Docker restart
└── update_repo.sh       → Git pull only (Docker tetap stop)

Tech Stack

Component	Technology
Backend API	Go 1.25, Gin, GORM
Database	PostgreSQL 16
Cache & Heartbeat	Redis 7
Firewall	nftables (google/nftables)
Tunneling	wireguard-go (userspace)
Cryptography	AES-256-GCM, SHA-256, bcrypt
Dashboard	Vue 3, Vite 8, Pinia, Tailwind CSS 4
CI/CD	Gitea Actions

Quick Reference

# Start all services
./setup.sh

# Update code + restart (Docker down → git pull → docker up)
./upgrade.sh

# Update code only (Docker tetap stop)
./update_repo.sh

# Create admin via Docker
docker compose exec server-core ./server-core -create-admin -user admin -pass "pass123"

# View logs
docker compose logs -f server-core

# Rebuild + restart
docker compose up -d --build

# Stop everything
docker compose down