docs: fix main README — fix URLs, add docker admin guide, reference commands

2026-05-16 01:21:26 +07:00
parent 06b7d2f9bf
commit aeca08cbd1
1 changed files with 142 additions and 22 deletions
@@ -3,35 +3,155 @@
 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)](apps/server-core/README.md)**: The central API and VPN Hub managing IPAM, routing, and `nftables` isolation.
-2. **[Dashboard UI](apps/dashboard-ui/README.md)**: The Admin web interface for managing users, devices, and firewall rules.
-3. **[Device Agent](apps/device-agent/README.md)**: A stealth background service for client machines that establishes secure WireGuard tunnels.
+
+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. Initial Setup & Creating the Admin (Terminal)
-For maximum security, the initial administrator account **cannot** be created via the web. It must be created directly on the server via the terminal.
-Inside the `apps/server-core` directory (or inside your docker container), run:
-```bash
-go run . -create-admin -user "admin" -pass "YourSecurePassword123"
-```
-*(This command creates the superuser `admin` in the database).*
+### 1. Clone Repository

-### 2. Creating Regular Users (Web Dashboard)
-1. Open the **Dashboard UI** in your web browser.
-2. Log in using the `admin` credentials created in Step 1.
-3. Once logged in as `admin`, you have the authorization to create regular User accounts for your team members.
-*(Note: Public registration is disabled. Only the `admin` can provision new users).*
-
-### 3. Registering a Device
-1. A User logs into the Dashboard UI using their assigned account.
-2. They click **"+ New Device"** and enter a recognizable name (e.g., "Johns-Laptop").
-3. The Dashboard will display a one-time **Registration Token**. 
-4. The user copies this token and runs the agent installer on their machine:
 ```bash
-   sudo ./install_agent.sh --server-url "http://<SERVER_IP>:8080" --token "<REGISTRATION_TOKEN>"
+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
 ```
-5. The device connects, binds its Hardware ID securely, provisions its WireGuard keys, and appears as **Online** in the Dashboard.