diff --git a/README.md b/README.md index f82048b..319deec 100644 --- a/README.md +++ b/README.md @@ -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: +### 1. Clone Repository + ```bash -go run . -create-admin -user "admin" -pass "YourSecurePassword123" +git clone --recursive http://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git +cd Nexus-Guard-Suite ``` -*(This command creates the superuser `admin` in the database).* -### 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).* +### 2. Start Infrastructure (Docker) -### 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://:8080" --token "" - ``` -5. The device connects, binds its Hardware ID securely, provisions its WireGuard keys, and appears as **Online** in the Dashboard. +```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://:8080" \ + --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 +```