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](http://git.datadunia.com/nexusguard/nexus-server-core)**: The central API and VPN Hub managing database state, token distribution, and Linux firewall isolation.
2. **[Dashboard UI](http://git.datadunia.com/nexusguard/nexus-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](http://git.datadunia.com/nexusguard/nexus-device-agent)**: A stealth background daemon for Linux/Windows/macOS client machines that establishes memory-injected WireGuard tunnels.
4. **[Device Agent Embedded](http://git.datadunia.com/nexusguard/nexus-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:

```bash
git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite
bash update.sh              # Auto-generates .env + pulls, builds, migrates, starts
```

The first run will automatically:
- Generate `.env` from `.env.example` with auto-generated JWT/SALT keys.
- Pull the latest code and build the Docker containers.
- Auto-generate the **Local Primary Node** WireGuard keys on the first boot.
- Create the database schema via automated migration.

Edit `.env` afterward to customize `DB_PASSWORD`, `API_PORT`, `VITE_API_BASE_URL`.

**Update Options:**
```bash
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:**
```bash
# 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**
```bash
# 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**
```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
```

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**
```bash
sudo /usr/local/bin/nexusguard-server -create-admin -user "admin" -pass "YourSecurePassword!"
```

**4. Uninstall**
```bash
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)**
```bash
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)**
```bash
cd apps/dashboard-ui
npm install
npm run dev
```

**4. Create Admin Account**
In a new terminal:
```bash
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:**
```bash
docker exec -it nexus-guard-suite-server-core-1 ./server-core -create-admin -user "admin" -pass "YourNewSecurePassword123!"
```

**Native:**
```bash
sudo /usr/local/bin/nexusguard-server -create-admin -user "admin" -pass "YourNewSecurePassword123!"
```

**Development:**
```bash
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:
   ```bash
   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

```bash
cd apps/docs
npm install
npm run docs:dev
```

### Building Docs

```bash
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 + auto-setup script
├── nexusguard-install.sh   # Native install script
├── nexusguard-uninstall.sh # Native uninstall script
├── .env.example            # Environment template
└── Makefile                # Quick commands
```