docs: finalize master architecture documentation and workflow

2026-05-16 01:25:56 +07:00
parent aeca08cbd1
commit b315870849
4 changed files with 39 additions and 139 deletions
@@ -1,157 +1,57 @@
 # NexusGuard SD-WAN Suite

-NexusGuard is an Enterprise Zero-Trust SD-WAN solution built with Go, Vue 3, and WireGuard.
-
-## System Architecture
+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 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)  │
-                   └──────────────┘             └──────────────┘
-```
+1. **[Server Core](apps/server-core/README.md)**: The central API and VPN Hub managing database state, token distribution, and Linux firewall isolation.
+2. **[Dashboard UI](apps/dashboard-ui/README.md)**: The Admin Web GUI for managing Nodes, Users, Devices, and Firewall rules.
+3. **[Device Agent](apps/device-agent/README.md)**: A stealth background daemon for Linux client machines that establishes memory-injected WireGuard tunnels.

 ---

-## Complete Workflow Guide
+## 🚀 Deployment & Installation

-### 1. Clone Repository
+### 1. Initial Setup
+To deploy the entire backend infrastructure (PostgreSQL, Redis, and Server-Core), simply clone this repository and run the setup script:

 ```bash
-git clone --recursive http://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
+git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
 cd Nexus-Guard-Suite
+chmod +x setup.sh
+./setup.sh
 ```

-### 2. Start Infrastructure (Docker)
+The `setup.sh` script will automatically:
+- Create a master `.env` file (if it doesn't exist).
+- Boot up all required infrastructure via `docker-compose`.
+
+### 2. Domain & Port Configuration
+If you are deploying this to production, you must edit the `.env` file generated in the root directory:
+- **Change API Port**: Modify `API_PORT=8080`.
+- **Change Web/API Domain**: Modify `VITE_API_BASE_URL` to point to your public API domain (e.g., `https://api.yourdomain.com/api/v1`).
+- **Database & Crypto**: Ensure you change the default database passwords and generate secure 256-bit Hex keys for `JWT_SECRET` and `SERVER_SALT`.
+
+### 3. 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), you must execute a command directly inside the running Docker container:

 ```bash
-cp apps/server-core/.env.example .env
-# edit .env — at minimum ganti JWT_SECRET dan SERVER_SALT
-docker compose up -d
+docker exec -it nexus-guard-suite-server-core-1 ./server-core -create-admin -user "admin" -pass "YourNewSecurePassword123!"
 ```
-
-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.
+*(You can use this exact same command later if you ever forget the admin password to forcefully reset it).*

 ---

-## Repository Structure
+## 📖 Operational Workflow

-```
-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)
-```
+Once the server is running and the Admin account is created, follow this flow:

-## 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
-```
+1. **Log in to the Dashboard UI** using the `admin` credentials.
+2. **Register a WireGuard Node**: Go to the **Nodes** menu. Add your public WireGuard server endpoint (e.g., `vpn.yourdomain.com:51820`) and its Public Key.
+3. **Add a Device**: Go to the **Devices** menu. Click **+ New Device**, select the target Node, and name the device.
+4. **Copy the Token**: The system will display a single-use **Registration Token**.
+5. **Install the Agent on Client**: On the target Linux machine, run the agent installer:
+   ```bash
+   sudo ./install_agent.sh --server-url "https://api.yourdomain.com" --token "<REG_TOKEN>"
+   ```
+6. The client will automatically connect, provision its WireGuard keys securely via AES-256-GCM, and appear as **Online** on your Dashboard.