docs: update AGENTS.md and README.md for WGRplane integration

- Add WGRplane component documentation to AGENTS.md - Update README.md with combined WireGuard Policy + WGRplane docs - Fix .gitignore (remove .gitea/ from ignore)
2026-05-06 05:23:00 +07:00
parent b3676b87cb
commit 52e629ac02
3 changed files with 310 additions and 4 deletions
@@ -1,8 +1,29 @@
-# WireGuard Dynamic Policy Firewall
+# WireGuard Policy Firewall + WGRplane Control Plane

-A lightweight, robust, and highly dynamic iptables/ipset policy firewall engine designed to restrict and control WireGuard peer traffic (egress traffic mapping) straight from `wg0.conf`. 
+A complete WireGuard management solution combining two powerful components:

-Rather than allowing all VPN clients to reach any part of your internal network, this tool isolates clients from each other by default and reads a custom `#Access` comment inside `wg0.conf` to automatically generate strict `iptables` rules and `ipset` whitelists per-client on the fly.
+1. **WireGuard Dynamic Policy Firewall** - A lightweight, robust iptables/ipset policy engine that restricts and controls WireGuard peer traffic directly from `wg0.conf` using custom `#Access` comments.
+2. **WGRplane** - A Go-native control plane application with Vue 3 frontend, providing a modern web dashboard for WireGuard management with real-time monitoring, peer CRUD, and hybrid firewall enforcement.
+
+---
+
+## 📑 Table of Contents
+
+### Policy Firewall (Shell Scripts)
+- [Architecture & Data Flow](#-architecture--data-flow)
+- [Installation](#-installation)
+- [Prerequisites](#-prerequisites)
+- [wg0.conf Integration](#-integrasi-ke-wg0conf)
+- [CLI Usage](#-wg-policy-ctl-cli-usage)
+- [Systemd Integration](#-systemd-integration-watcher-daemon)
+
+### WGRplane (Go App)
+- [WGRplane Overview](#-wgrplane-overview)
+- [WGRplane Architecture](#-wgrplane-architecture)
+- [WGRplane Features](#-wgrplane-features)
+- [WGRplane Tech Stack](#-wgrplane-tech-stack)
+- [WGRplane API Endpoints](#-wgrplane-api-endpoints)
+- [WGRplane Installation](#-wgrplane-installation)

 ---

@@ -171,3 +192,210 @@ Check the watcher logs:
 ```bash
 journalctl -u wg-policy.service -f
 ```
+
+---
+
+## 🚀 WGRplane Overview
+
+**WGRplane** is a Go-native WireGuard control plane application with a Vue 3 frontend, providing a modern web dashboard for WireGuard management. It features a single Go binary backend, SPA frontend, dynamic policy firewall integration, and glassmorphism UI design.
+
+The application lives in the `/app` directory. For full documentation, see [`app/README.md`](app/README.md).
+
+---
+
+## 🏗 WGRplane Architecture
+
+```
+wg0.conf (with/without #Access)
+        ↓
+┌─────────────────────────────────────────────┐
+│  WGRplane (Go Binary :10087)                │
+│  ┌───────────┐  ┌──────────┐  ┌──────────┐  │
+│  │ Gorilla   │  │ GORM     │  │ nftables │  │
+│  │ Mux Router│  │ SQLite   │  │ Engine   │  │
+│  └───────────┘  └──────────┘  └──────────┘  │
+│  ┌───────────┐  ┌──────────┐  ┌──────────┐  │
+│  │ Webhook   │  │ Scheduler│  │ WebSocket│  │
+│  │ Engine    │  │ Cron     │  │ Hub      │  │
+│  └───────────┘  └──────────┘  └──────────┘  │
+│  ┌───────────┐  ┌──────────┐  ┌──────────┐  │
+│  │ Auth      │  │ SMTP     │  │ Plugins  │  │
+│  │ JWT/TOTP  │  │ Email    │  │ TG/Slack │  │
+│  └───────────┘  └──────────┘  └──────────┘  │
+└─────────────────────────────────────────────┘
+        ↓ HTTP/WebSocket
+┌─────────────────────────────────────────────┐
+│  Frontend (Vue 3 + TypeScript + Tailwind)   │
+│  Glassmorphism UI, i18n, Dark/Light mode    │
+└─────────────────────────────────────────────┘
+```
+
+### Hybrid Mode
+
+WGRplane supports two server modes:
+
+- **`forward`** - Directly applies nftables rules on the local machine. Peer policies are enforced via `nft` commands.
+- **`standalone`** - Acts as a control plane that triggers webhooks to remote WireGuard servers. Policy enforcement happens on the remote side.
+
+### 2-Column Policy
+
+Each peer has two independent policy columns:
+
+| Column | Function |
+|--------|----------|
+| **AllowAccess** | List of CIDRs the peer can access (internal targets) |
+| **AllowInternet** | Boolean flag. If `true`, peer gets unlimited internet access (MASQUERADE) |
+
+Peers without any rules are isolated from other peers and the internet by default.
+
+---
+
+## ✨ WGRplane Features
+
+- **Go-Native Architecture**: Single Go binary handles all API, database, webhooks, scheduler, and nftables. No Python/Flask needed.
+- **Complete Peer CRUD**: Add, edit, delete peers. Generate QR codes for mobile client import. Export `.conf` configuration files.
+- **Hybrid Mode**: `forward` mode (local nftables) or `standalone` mode (webhook to remote servers).
+- **2-Column Policy UI**: "Allow Access" column (firewall whitelist CIDR) and "Allow Internet" toggle per peer.
+- **Real-time Monitoring**: WebSocket broadcasts peer statistics and traffic every 5 seconds.
+- **Automated Scheduling**: Daily cron jobs to delete expired peers, restrict over-limit peers, and reset monthly data usage.
+- **Security**: API Key authentication (`wg-rplane-datadunia`), JWT Bearer tokens, and TOTP (2FA).
+- **Webhook Engine**: Integration with remote servers (Mikrotik, etc.). Retry with exponential backoff, custom headers, Go templates.
+- **Plugin System**: Telegram, Slack, and Traffic Logger notifications.
+- **i18n & Themes**: Multi-language (English, Indonesian, Chinese). Dark/Light/Auto mode.
+- **Glassmorphism UI**: Futuristic design with frosted glass cards, buttons, and inputs.
+
+---
+
+## 🛠 WGRplane Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| **Backend** | Go, Gorilla Mux, GORM (SQLite via glebarez/sqlite) |
+| **Frontend** | Vue 3, TypeScript, Vite, TailwindCSS 4, vue-i18n 9 |
+| **Auth** | JWT (golang-jwt/v5), TOTP (pquerna/otp), API Key |
+| **WebSockets** | gorilla/websocket |
+| **Webhooks** | Go net/http with retry + exponential backoff |
+| **Scheduling** | robfig/cron v3 |
+| **QR Code** | skip2/go-qrcode |
+| **Email** | jordan-wright/email (SMTP) |
+| **Firewall** | Bash, iptables, ipset, nftables, inotify-tools, jq |
+| **Container** | Docker (multi-stage build), docker-compose |
+
+---
+
+## 🌐 WGRplane API Endpoints Summary
+
+All endpoints are served on port **10087**. For complete API documentation with request/response details, see [`app/README.md`](app/README.md) or visit `/swagger/` on your running instance.
+
+### Authentication
+
+| Method | Header | Notes |
+|--------|--------|-------|
+| API Key | `wg-rplane-datadunia: <KEY>` | Set via env var `WG_API_KEY`. Default: `test-api-key` |
+| JWT | `Authorization: Bearer <TOKEN>` | Expires in 15 minutes. Secret via env var `JWT_SECRET` |
+| TOTP | `X-TOTP: <CODE>` | Required if user enables TOTP |
+
+### Main Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/servers` | `GET/POST` | List all servers / Create new server |
+| `/api/servers/{id}` | `GET/PUT/DELETE` | Get/Update/Delete server |
+| `/api/servers/{id}/peers` | `GET/POST` | List peers / Create new peer |
+| `/api/peers/{id}` | `PUT/DELETE` | Update/Delete peer |
+| `/api/peers/{id}/config` | `GET` | Download WireGuard `.conf` file |
+| `/api/peers/{id}/qrcode` | `GET` | Generate QR code PNG for mobile import |
+| `/api/servers/{id}/webhooks` | `GET/POST` | List/Create webhooks |
+| `/api/stats` | `GET` | Global statistics |
+| `/ws/stats` | WebSocket | Real-time stats broadcast (5s interval) |
+| `/swagger/` | - | Interactive Swagger UI documentation |
+
+---
+
+## 📦 WGRplane Installation
+
+### Option 1: Docker Compose (Recommended)
+
+```bash
+# Clone repository
+git clone https://git.datadunia.com/hainzero/WGRplane.git
+cd 03.wireguard-policy
+
+# Start WGRplane and WireGuard
+docker compose up -d
+
+# Access dashboard at http://localhost:10087
+```
+
+### Option 2: Install Script
+
+```bash
+# Run automated installer (Ubuntu/Debian/CentOS)
+sudo ./install.sh install
+
+# Uninstall
+sudo ./install.sh uninstall
+```
+
+### Option 3: Manual Build
+
+```bash
+# Build Go binary
+cd app
+go build -o ../wgrplane .
+cd ..
+
+# Build frontend
+cd app/frontend
+npm install && npm run build
+cd ../..
+
+# Run
+./wgrplane
+# Server starts on :10087
+```
+
+### Option 4: Systemd Service
+
+```bash
+# Install service file
+sudo cp wgrplane.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable wgrplane.service
+sudo systemctl start wgrplane.service
+
+# View logs
+journalctl -u wgrplane.service -f
+```
+
+---
+
+## 📁 Project Structure
+
+```
+03.wireguard-policy/
+├── app/                          # Go backend + Vue frontend
+│   ├── main.go                   # Bootstrap server, routing, init DB
+│   ├── handlers.go               # REST API route handlers
+│   ├── models.go                 # GORM models (Server, Peer, Webhook, SMTP)
+│   ├── auth.go                   # JWT, TOTP, API key auth middleware
+│   ├── nftables.go               # nftables rule management (mode forward)
+│   ├── webhook.go                # Webhook engine with retry/backoff
+│   ├── scheduler.go              # Cron jobs (expiry, data limit, reset)
+│   ├── stats.go                  # WebSocket Hub for real-time stats
+│   ├── frontend/                 # Vue 3 SPA (TypeScript, TailwindCSS)
+│   └── docs/                     # Swagger documentation
+├── wg-sync-policy.sh             # Parse wg0.conf → policy.json
+├── wg-policy-engine.sh           # Apply policy.json → iptables/ipset
+├── wg-sync-watch.sh              # inotifywait watcher daemon
+├── wg-policy-ctl                 # CLI wrapper for policy management
+├── wg-policy-cleanup.sh          # Cleanup script for PostDown
+├── wg-policy.service             # Systemd unit for watcher daemon
+├── wgrplane.service              # Systemd unit for Go backend
+├── install.sh                    # Automated installer (Docker + services)
+├── Dockerfile                    # Multi-stage Docker build
+├── docker-compose.yml            # Docker Compose stack
+└── README.md                     # This file
+```
+
+For detailed WGRplane documentation including webhooks, plugins, scheduler, and frontend details, refer to [`app/README.md`](app/README.md).