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)](http://git.datadunia.com/nexusguard/nexus-server-core)** — The central API and VPN Hub managing IPAM, routing, and `nftables` isolation.
2. **[Dashboard UI](http://git.datadunia.com/nexusguard/nexus-dashboard-ui)** — The Admin web interface for managing users, devices, and firewall rules.
3. **[Device Agent](http://git.datadunia.com/nexusguard/nexus-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

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

### 2. Start Infrastructure (Docker)

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

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

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

```bash
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

```bash
# 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
```