nexusguard/Nexus-Guard-Suite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

docs: add NexusGuard portfolio (architecture, tech-stack, features, deployment)

Browse Source
This commit is contained in:
datadunia
2026-06-21 14:25:33 +07:00
parent a485c8df42
commit d6c53f6f86
6 changed files with 1358 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/portfolio/README.md
+52
View File
@@ -0,0 +1,52 @@
# NexusGuard SD-WAN Suite
> Enterprise Zero-Trust SD-WAN with WireGuard
NexusGuard is a production-grade, 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 Linux `nftables` — all managed through a futuristic glassmorphism dashboard.
## Key Highlights
- **Zero-Attack Surface** — No public registration. Admin accounts created via CLI only.
- **Stealth Agent** — WireGuard config injected into memory. No files written to `/etc/wireguard/`.
- **Real-time Firewall** — Per-peer nftables rules synced to kernel instantly.
- **Cross-Platform** — Agent runs on Linux (daemon), Windows (tray + service), and macOS (tray).
## Tech Stack
`Go` · `Vue 3` · `WireGuard` · `PostgreSQL` · `Redis` · `nftables` · `gRPC` · `Docker`
## Architecture
```
┌──────────────┐ ┌─────────────────┐ ┌──────────────┐
│ Dashboard │──HTTP──▶│ Server Core │◀─WG────▶│ Device Agent │
│ (Vue 3) │ :8080 │ (Go/Gin) │ :51820 │ (Go) │
└──────────────┘ │ │ └──────────────┘
│ Port 8080: │ │
│ - HTTP API │ ┌────┴────┐
│ - gRPC Signal │ │ TUN (wg)│
│ (cmux) │ │ Memory │
└─────────────────┘ └─────────┘
```
## Documentation
| Document | Description |
|----------|-------------|
| [Architecture](architecture.md) | System architecture, data flow, security model |
| [Tech Stack](tech-stack.md) | Technology breakdown per component |
| [Features](features.md) | Feature showcase and capabilities |
| [Deployment](deployment.md) | Deployment guide (Docker, native, development) |
## Quick Start
```bash
git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite
./setup.sh
bash update.sh
```
## License
Private — DataDunia
docs/portfolio/architecture.md
+190
View File
@@ -0,0 +1,190 @@
# Architecture Overview
NexusGuard is a three-component SD-WAN system: a central API server, a web dashboard, and cross-platform device agents. All communication is encrypted. Tunnels are fileless. Access is zero-trust.
## High-Level Architecture
```
┌─────────────────────────────────────────────────────────────────────┐
│ Dashboard (Vue 3) │
│ Glassmorphism Web Interface │
│ Manages: Nodes, Devices, Rules │
└───────────────────────────────────┬─────────────────────────────────┘
│ HTTP (port 80)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Nginx Reverse Proxy │
│ Routes: /api/ → :8080, / → SPA │
└───────────────────────────────────┬─────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Server Core (Go/Gin) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ HTTP API │ │ gRPC │ │ IPAM │ │ nftables │ │
│ │ (20+ │ │ Signaling│ │ Manager │ │ Firewall │ │
│ │ handlers)│ │ (cmux) │ │ │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PostgreSQL Database │ │
│ │ (wg_servers, devices, rules, users) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ Redis │ │ WireGuard │ │
│ │ (Heartbeat TTL) │ │ (wg0 interface) │ │
│ └──────────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌───────────────────────────┐ ┌───────────────────────────┐
│ Device Agent (Linux) │ │ Device Agent (Win/Mac) │
│ Systemd Daemon │ │ System Tray │
│ Memory-injected WG │ │ Memory-injected WG │
└───────────────────────────┘ └───────────────────────────┘
```
## Component Breakdown
### Server Core
The central API and VPN hub. Written in Go with Gin framework.
| Responsibility | Implementation |
|----------------|----------------|
| API endpoints | 20+ Gin handlers (`api/` directory) |
| gRPC signaling | Bidirectional streaming via cmux (port 8080) |
| IPAM | IP pool allocation from CIDR per node |
| Firewall | nftables rule management (add/remove per peer) |
| WireGuard | Interface control, peer sync, config push |
| Auth | JWT middleware, admin-only enforcement |
| Heartbeat | Config sync, handshake monitoring |
### Dashboard UI
Admin web interface. Built with Vue 3 and glassmorphism design system.
| Responsibility | Implementation |
|----------------|----------------|
| Node management | Register/edit WireGuard servers |
| Device management | CRUD, provisioning tokens, QR codes |
| Firewall rules | Per-peer nftables rule editor |
| Live telemetry | 10s polling for device health |
| Traffic history | Time-range filtering, export |
### Device Agent
Stealth VPN daemon. Cross-platform Go binary.
| Responsibility | Implementation |
|----------------|----------------|
| Provisioning | HTTP POST with AES-256-GCM encrypted response |
| Tunnel | Memory-injected WireGuard (no disk files) |
| Heartbeat | HTTP/gRPC, config sync, handshake monitoring |
| gRPC | Bidirectional stream for real-time commands |
| Self-healing | Exponential backoff reconnection |
## Data Flow
### Provisioning Flow
```
1. Admin creates device via Dashboard → API generates registration token
2. Agent sends token + HWID to POST /api/v1/provision
3. Server validates token, allocates IP from pool
4. Server responds with WireGuard config (AES-256-GCM encrypted)
5. Agent decrypts config, injects into WireGuard via IpcSet
6. Tunnel established — no files written to disk
```
### Heartbeat Flow
```
Every 30 seconds:
1. Agent reads last_handshake_time from WireGuard IPC
2. Agent computes config_hash = endpoint + internalIP + serverPub
3. Agent POSTs {config_hash, last_handshake, tunnel_up} to server
4. Server compares with stored config
5. If config changed → server responds with new config
6. Agent detects change → rebuilds tunnel
```
### Suspend/Resume Flow
```
Suspend:
1. Admin clicks "Suspend" in Dashboard
2. Dashboard POSTs /api/v1/devices/:id/suspend
3. Server updates DB (is_suspended = true)
4. Server sends gRPC SuspendCommand to agent
5. Server removes WireGuard peer from kernel
6. Agent receives command → stops tunnel
Resume:
1. Admin clicks "Resume" in Dashboard
2. Server updates DB (is_suspended = false)
3. Server re-adds WireGuard peer to kernel
4. Server sends gRPC ResumeCommand with full ConfigUpdate
5. Agent receives command → rebuilds tunnel
```
## Security Model
### Zero-Trust Principles
| Principle | Implementation |
|-----------|----------------|
| No public registration | `/auth/register` locked; admin via CLI only |
| Encrypted provisioning | AES-256-GCM for WireGuard config transfer |
| Fileless tunnels | WireGuard config in process memory only |
| Hardware binding | HWID (DMI/CPU serial) bound to registration token |
| Per-peer isolation | nftables rules per device, default deny |
| JWT authentication | All API endpoints require valid token |
### Trust Boundaries
```
┌─────────────────────────────────────────────────────────┐
│ Trusted Zone │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │ Server │ │ Database │ │ WireGuard Interface │ │
│ │ Core │ │ (PG) │ │ (wg0) │ │
│ └──────────┘ └──────────┘ └──────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
│
Encrypted Channel
(AES-256-GCM / WG)
│
┌─────────────────────────────────────────────────────────┐
│ Untrusted Zone │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Device Agent │ │
│ │ (Memory-only WireGuard config) │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
## Port Multiplexing
Server Core uses cmux to serve both HTTP and gRPC on port 8080:
```go
m := cmux.New(lis)
grpcLis := m.MatchWithWriters(cmux.HTTP2MatchHeaderFieldSendSettings(
"content-type", "application/grpc",
))
httpLis := m.Match(cmux.Any())
```
- gRPC matched by `content-type: application/grpc` header
- HTTP matched by `Any()` (catch-all)
- Single port, single listener, zero extra config
docs/portfolio/deployment.md
+482
View File
@@ -0,0 +1,482 @@
# 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
```bash
# Clone repository
git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite
# Generate .env file
./setup.sh
# Edit configuration
nano .env
# Start all services
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:
```bash
# 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 setup.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
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
```bash
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:**
```bash
sudo apt install -y golang nginx postgresql redis-server nftables wireguard-tools
```
**CentOS/Rocky:**
```bash
sudo dnf install -y golang nginx postgresql-server redis nftables wireguard-tools
```
### Build Binaries
**Server Core:**
```bash
cd apps/server-core
CGO_ENABLED=0 go build -o ../../bin/server-core .
cd ../..
```
**Dashboard UI:**
```bash
cd apps/dashboard-ui
npm install
VITE_API_BASE_URL=/api/v1 npm run build
cd ../..
```
### Run Installer
```bash
sudo bash nexusguard-install.sh
```
**Options:**
```bash
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
```bash
sudo /usr/local/bin/nexusguard-server \
-create-admin -user admin -pass "YourSecurePassword123!"
```
### Service Management
```bash
# 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`:
```bash
# 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
```bash
# 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:
```sql
CREATE DATABASE nexusguard;
CREATE USER nexusguard WITH PASSWORD 'nexusguard';
GRANT ALL PRIVILEGES ON DATABASE nexusguard TO nexusguard;
```
2. Copy environment template:
```bash
cp .env.example .env
```
3. Edit `.env` with your database credentials.
### Start Backend
```bash
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
```bash
cd apps/dashboard-ui
npm install
npm run dev
```
Dashboard available at `http://localhost:5173`.
### Create Admin Account
```bash
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)
```bash
# 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)
```bash
# 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:
```bash
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 `%APPDATA%\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
```bash
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) | `%APPDATA%\NexusGuard\logs\` |
| Agent (macOS) | `~/Library/Logs/NexusGuard/` |
### Debug Commands
```bash
# 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
```
docs/portfolio/features.md
+291
View File
@@ -0,0 +1,291 @@
# Features
NexusGuard provides enterprise-grade SD-WAN capabilities with a focus on security, automation, and ease of use.
## Zero-Trust Security
### No Public Registration
The `/auth/register` endpoint is locked. Admin accounts can only be created via CLI:
```bash
# Docker
docker exec -it nexus-guard-suite-server-core-1 ./server-core \
-create-admin -user admin -pass "SecurePassword123!"
# Native
sudo /usr/local/bin/nexusguard-server \
-create-admin -user admin -pass "SecurePassword123!"
```
**Why?** Eliminates the attack surface of open registration. No bots, no brute force, no unauthorized accounts.
### Encrypted Provisioning
Agent provisioning uses AES-256-GCM encryption:
1. Agent sends registration token + hardware ID (HWID)
2. Server generates WireGuard config
3. Config encrypted with AES-256-GCM before transmission
4. Agent decrypts in memory, never touches disk
**Why?** WireGuard keys are sensitive. Encryption in transit prevents interception even on compromised networks.
### Memory-Injected Tunnels
WireGuard configuration is injected directly into the kernel via `IpcSet`:
```
Traditional: Config file → /etc/wireguard/wg0.conf → wg-quick up wg0
NexusGuard: Config bytes → IpcSet() → Tunnel active (no files)
```
**Benefits:**
- No config files to steal
- No lingering configs after disconnect
- Multiple agents can run without conflicts
- Clean uninstall = kill process
### Hardware ID Binding
Each agent is bound to its hardware via HWID:
- **Linux:** `/sys/class/dmi/id/product_uuid` or CPU serial
- **Windows:** DMI product UUID
- **macOS:** IOPlatformSerialNumber
HWID is included in provisioning request. Server validates before issuing config.
## Multi-Node Support
### Geographic Scaling
Deploy WireGuard servers across multiple regions:
```
Node 1 (Singapore): 10.172.21.0/24
Node 2 (Frankfurt): 10.172.22.0/24
Node 3 (Virginia): 10.172.23.0/24
```
Each node has its own:
- IP pool (CIDR)
- Interface address
- Peer defaults (DNS, MTU, Keepalive)
- Endpoint (IP/Domain + Port)
### Centralized IPAM
IP Address Management is centralized in the database:
1. Admin defines IP pool per node (e.g., `10.172.21.0/24`)
2. When device is created, server allocates next available IP
3. IP is reserved in database (no duplicates)
4. IP is released when device is deleted
**Why?** Prevents IP conflicts across nodes. Enables static IP assignment for critical devices.
### Per-Node Defaults
Each node can have different peer defaults:
| Setting | Node 1 (SG) | Node 2 (DE) |
|---------|-------------|-------------|
| DNS | `1.1.1.1` | `8.8.8.8` |
| MTU | 1420 | 1280 |
| Keepalive | 25s | 0s |
| AllowedIPs | `10.172.21.0/24` | `0.0.0.0/0` |
Devices inherit from their node, with per-device overrides available.
## Real-Time Firewall
### nftables Integration
NexusGuard manages Linux nftables directly:
```bash
# What NexusGuard creates in the kernel
table ip nexusguard {
set peers_v4 {
type ipv4_addr
elements = { 10.172.21.2, 10.172.21.3, ... }
}
chain forward {
type filter hook forward priority 0; policy accept;
ip daddr @peers_v4 accept
ip saddr @peers_v4 accept
drop
}
}
```
### Per-Peer Rules
Each device can have custom firewall rules:
- **Allow/Block IP ranges** — `192.168.1.0/24`, `10.0.0.1`
- **Port filtering** — TCP/UDP port ranges
- **Direction control** — Inbound, outbound, or both
Changes are synced to kernel instantly — no restart required.
### Default SSH Provisioning
New peers automatically get SSH access (port 22):
```go
// Automatically added on peer creation
AddFirewallRule(peerIP, "0.0.0.0/0", 22, "tcp", "allow")
```
**Why?** Ensures remote access isn't accidentally locked out.
## Cross-Platform Agent
### Linux — Systemd Daemon
```bash
# Automated install
sudo ./install_agent.sh \
--server-url "https://api.yourdomain.com" \
--token "REG_TOKEN"
# Verify
sudo systemctl status sys-bridge.service
```
Features:
- Runs as root (required for WireGuard)
- Auto-restart on failure
- Journal logging
- Config at `~/.config/nexusguard/nexusguard.conf`
### Windows — System Tray + Service
System tray application with service management:
| Menu Item | Action |
|-----------|--------|
| Status | Shows Connected/Disconnected |
| IP | Shows internal VPN IP |
| Connect | Start tunnel |
| Disconnect | Stop tunnel |
| Install as Service | Register Windows service |
| Start on Boot | Toggle auto-start |
### macOS — System Tray
System tray application (no service support):
- Config at `~/Library/Application Support/NexusGuard/nexusguard.conf`
- Logs at `~/Library/Logs/NexusGuard/`
### Self-Healing
All platforms implement exponential backoff:
```
Failure 1: Wait 30s, retry
Failure 2: Wait 60s, retry
Failure 3: Wait 120s, retry
...
Failure N: Wait 300s (max), retry
```
Network drops are handled gracefully — tunnel stays alive, agent reconnects in background.
## Dashboard
### Glassmorphism Design
Futuristic UI with glass-like transparency:
- Backdrop blur effects
- Semi-transparent panels
- Gradient accents
- Smooth animations
### Live Telemetry
Device health polled every 10 seconds:
```
┌─────────────────────────────────────────┐
│ Device: server-01 │
│ Status: ● Online │
│ IP: 10.172.21.2 │
│ Last Handshake: 15s ago │
│ Uptime: 3d 14h 22m │
└─────────────────────────────────────────┘
```
### QR Code Setup
Generate QR codes for mobile WireGuard clients:
1. Create device in Dashboard
2. Click "Show QR Code"
3. Scan with WireGuard app on iOS/Android
4. Tunnel ready — no manual config
### Share Links
Time-limited config sharing:
1. Click "Generate Share Link"
2. Set expiration (1h, 24h, 7d)
3. Share URL with recipient
4. Recipient downloads `.conf` file
5. Link expires automatically
## Deployment Flexibility
### Docker (Recommended)
```bash
git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite
./setup.sh
bash update.sh
```
One command to start everything. Auto-migration on first boot.
### Native Install
For servers without Docker:
```bash
sudo bash nexusguard-install.sh
```
Creates systemd service, nginx config, PostgreSQL database.
### Development Mode
Hot-reload for both backend and frontend:
```bash
# Terminal 1: Backend
cd apps/server-core
go run -tags dev .
# Terminal 2: Frontend
cd apps/dashboard-ui
npm run dev
```
Auto-migration on startup. No Docker required.
## Comparison
| Feature | NexusGuard | Traditional VPN | Commercial SD-WAN |
|---------|------------|-----------------|-------------------|
| Zero-trust | ✅ | ❌ | ✅ |
| Fileless tunnel | ✅ | ❌ | ❌ |
| Multi-platform agent | ✅ | Partial | ✅ |
| Real-time firewall | ✅ | ❌ | ✅ |
| Self-hosted | ✅ | ✅ | ❌ |
| Open source | ✅ | ✅ | ❌ |
| Cost | Free | Free | $$$$ |
docs/portfolio/tech-stack.md
+134
View File
@@ -0,0 +1,134 @@
# Technology Stack
NexusGuard uses a modern, production-grade technology stack. Each component is built with tools optimized for its domain.
## Backend — Server Core
| Technology | Version | Purpose |
|------------|---------|---------|
| Go | 1.25+ | Primary language |
| Gin | 1.12 | HTTP framework |
| GORM | 1.31 | ORM (PostgreSQL) |
| grpc-go | latest | gRPC signaling |
| cmux | latest | Port multiplexing (HTTP + gRPC on :8080) |
| go-redis | 9.x | Heartbeat TTL cache |
| google/nftables | 0.3 | Linux firewall management |
| wgctrl | latest | WireGuard interface control |
| JWT v5 | latest | Authentication tokens |
### Why Go?
- **Static binaries** — No runtime dependencies, easy deployment
- **Concurrency** — Goroutines for handling 10000+ concurrent agent connections
- **WireGuard ecosystem** — Native Go WireGuard libraries (wgctrl, wireguard-go)
- **Performance** — Low memory footprint, fast cold start
### Why cmux?
Single port for HTTP and gRPC eliminates:
- Firewall rules for multiple ports
- Load balancer complexity
- Docker port mapping overhead
## Frontend — Dashboard UI
| Technology | Version | Purpose |
|------------|---------|---------|
| Vue | 3.5 | UI framework (Composition API) |
| Vite | 8 | Build tool + dev server |
| TypeScript | 6.0 | Type safety |
| TailwindCSS | 4.3 | Styling (glassmorphism design system) |
| Pinia | 2.3 | State management |
| Axios | 1.16 | HTTP client |
| HeadlessUI | 1.7 | Accessible UI primitives |
| Iconify | 5.0 | Icon system |
| VueUse | 14.3 | Composition utilities |
### Why Vue 3?
- **Composition API** — Better TypeScript support, reusable logic via composables
- **`<script setup>`** — Cleaner SFC syntax, less boilerplate
- **Ecosystem** — Mature ecosystem with Pinia, Vue Router, VueUse
### Why TailwindCSS 4?
- **Design tokens** — `@theme` block for consistent colors, spacing, typography
- **Glassmorphism** — Utility classes for backdrop-blur, transparency, gradients
- **No PostCSS** — Uses `@tailwindcss/vite` plugin (faster builds)
## Client — Device Agent
| Technology | Version | Purpose |
|------------|---------|---------|
| Go | 1.25+ | Primary language |
| wireguard-go | latest | Userspace WireGuard |
| fyne.io/systray | latest | Cross-platform system tray |
| wintun | latest | Windows WireGuard driver |
### Cross-Compile Targets
| Platform | Architecture | Binary |
|----------|--------------|--------|
| Linux | amd64 | `nexusguard-device-agent-linux-amd64` |
| Linux | arm64 | `nexusguard-device-agent-linux-arm64` |
| Linux | arm | `nexusguard-device-agent-linux-arm` |
| Windows | amd64 | `nexusguard-device-agent-gui.exe` |
| macOS | arm64 | `nexusguard-device-agent-darwin-arm64` |
| macOS | amd64 | `nexusguard-device-agent-darwin-amd64` |
### Why Memory-Injected Tunnels?
Traditional WireGuard setups write config to `/etc/wireguard/`. NexusGuard avoids this:
1. **Security** — No config files on disk = no file theft risk
2. **Stealth** — Tunnel exists only in process memory
3. **Cleanup** — Process exit = tunnel gone (no lingering configs)
4. **Multi-tenant** — Multiple agents can run without config conflicts
## Infrastructure
| Technology | Purpose |
|------------|---------|
| PostgreSQL | Primary database (wg_servers, devices, rules, users) |
| Redis | Heartbeat TTL cache, session tracking |
| nginx | Reverse proxy, SPA fallback, API routing |
| Docker | Container orchestration |
| docker-compose | Multi-service deployment |
### Why PostgreSQL?
- **ACID compliance** — Critical for IPAM allocation (no duplicate IPs)
- **JSON support** — Flexible config storage
- **Maturity** — Battle-tested for production workloads
### Why Redis?
- **Heartbeat TTL** — Fast expiry checks for agent health
- **Session cache** — gRPC session tracking
- **Pub/Sub** — Real-time event distribution (future)
## Build & CI
| Tool | Purpose |
|------|---------|
| Go build | Static binary compilation |
| Vite build | SPA bundling (vue-tsc + vite) |
| Gitea Actions | CI/CD per submodule |
| Makefile | Quick commands (up, down, dev, migrate) |
### Build Flags
```bash
# Server Core (production)
CGO_ENABLED=0 go build -o server-core .
# Device Agent (stripped)
go build -ldflags="-s -w" -o device-agent .
# Dashboard UI
VITE_API_BASE_URL=/api/v1 npm run build
```
- `CGO_ENABLED=0` — Static binary, no CGO dependencies
- `-ldflags="-s -w"` — Strip debug symbols (~30% smaller binary)
- `VITE_API_BASE_URL` — Build-time API endpoint injection