docs: update README for Forgejo migration and new features
- Update install script URL to src.d3v.ac - Update Docker image reference to src.d3v.ac/xtcnet/d3v-server:latest - Update git clone URL to Forgejo - Add Forgejo integration section (optional Git server + CI/CD) - Add encrypted file storage and client isolation to feature list - Update menu options to reflect current install.sh (8 options + Forgejo submenu) - Update CI/CD section to describe Forgejo Actions workflow Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
xtcnet
parent
b8d64b150c
commit
71f5477db3
1 changed files with 69 additions and 110 deletions
179
README.md
179
README.md
|
|
@ -1,71 +1,63 @@
|
|||
# D3V-NPMWG — xGat3 + WireGuard VPN
|
||||
|
||||
A powerful, all-in-one Docker container that combines **xGat3** (reverse proxy with SSL) and **WireGuard VPN** management in a single, beautiful web interface.
|
||||
A powerful, all-in-one Docker container that combines **xGat3** (reverse proxy with SSL) and **WireGuard VPN** management in a single web interface.
|
||||
|
||||
## ✨ Features
|
||||
## Features
|
||||
|
||||
### xGat3
|
||||
- 🌐 Reverse proxy management with a beautiful UI
|
||||
- 🔒 Free SSL certificates via Let's Encrypt
|
||||
- 🔀 Proxy hosts, redirection hosts, streams, and 404 hosts
|
||||
- 🛡️ Access control lists
|
||||
- 📊 Audit logging
|
||||
- Reverse proxy management with SSL (Let's Encrypt)
|
||||
- Proxy hosts, redirection hosts, streams, and 404 hosts
|
||||
- Access control lists and audit logging
|
||||
|
||||
### WireGuard VPN Manager
|
||||
- 🔑 Create, enable, disable, and delete VPN clients
|
||||
- 📱 QR code generation for mobile clients
|
||||
- 📥 Download `.conf` configuration files
|
||||
- 📡 Real-time client status (connected, idle, data transfer)
|
||||
- ⏰ Client expiration support
|
||||
- 🔄 Auto-sync WireGuard configs
|
||||
- Create, enable, disable, and delete VPN clients
|
||||
- QR code generation for mobile clients
|
||||
- Download `.conf` configuration files
|
||||
- Real-time client status (connected, idle, data transfer)
|
||||
- Client expiration support
|
||||
- Auto-sync WireGuard configs
|
||||
- Client isolation (block inter-client traffic)
|
||||
- Encrypted per-client file storage
|
||||
|
||||
## 🚀 Quick Start (Auto Install)
|
||||
### Forgejo Integration (optional)
|
||||
- Self-hosted Git server on the same VPS
|
||||
- Accessible only via domain through NPM proxy
|
||||
- CI/CD via Forgejo Runner for automated Docker builds
|
||||
|
||||
The easiest way to install, update, and manage your D3V-NPMWG instance on Linux is by using our interactive manager script.
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Download and run the install script
|
||||
curl -sSL https://raw.githubusercontent.com/xtcnet/D3V-NPMWG/master/install.sh -o install.sh
|
||||
curl -sSL https://src.d3v.ac/xtcnet/D3V-Server/raw/branch/master/install.sh -o install.sh
|
||||
chmod +x install.sh
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
**Features included in the script:**
|
||||
- `Install D3V-NPMWG`: Automatically setup docker-compose and directories in `/opt/d3v-npmwg`.
|
||||
- `Uninstall D3V-NPMWG`: Remove containers and wipe data.
|
||||
- `Reset Password`: Resets the admin login to `admin@example.com` / `changeme`.
|
||||
- `Update`: Pulls the latest image and updates the docker-compose stack.
|
||||
**Menu options:**
|
||||
- `1` Install D3V-NPMWG
|
||||
- `2` Uninstall D3V-NPMWG
|
||||
- `3` Uninstall D3V-NPMWG + Docker (Purge)
|
||||
- `4` Reset Admin Password
|
||||
- `5` Update D3V-NPMWG
|
||||
- `6` Manage Custom Stream Ports
|
||||
- `7` Toggle Admin Port 81 (Block/Unblock)
|
||||
- `8` Forgejo → Install / Uninstall / Update / Install Runner / Uninstall Runner
|
||||
|
||||
You can also run specific commands directly: `sudo ./install.sh {install|uninstall|reset|update}`
|
||||
You can also run commands directly:
|
||||
```bash
|
||||
sudo ./install.sh {install|uninstall|purge|reset|update|manage-ports|toggle-port|forgejo}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐋 Manual Docker Run```bash
|
||||
docker run -d \
|
||||
--name npm-wg \
|
||||
--cap-add=NET_ADMIN \
|
||||
--cap-add=SYS_MODULE \
|
||||
--sysctl net.ipv4.ip_forward=1 \
|
||||
--sysctl net.ipv4.conf.all.src_valid_mark=1 \
|
||||
-p 80:80 \
|
||||
-p 81:81 \
|
||||
-p 443:443 \
|
||||
-p 51820-51830:51820-51830/udp \
|
||||
-v npm-wg-data:/data \
|
||||
-v npm-wg-letsencrypt:/etc/letsencrypt \
|
||||
-v npm-wg-wireguard:/etc/wireguard \
|
||||
-e WG_HOST=your.server.ip \
|
||||
npm-wg:latest
|
||||
```
|
||||
|
||||
## 📋 Docker Compose
|
||||
## Manual Docker Compose
|
||||
|
||||
```yaml
|
||||
version: "3.8"
|
||||
services:
|
||||
npm-wg:
|
||||
image: npm-wg:latest
|
||||
container_name: npm-wg
|
||||
d3v-npmwg:
|
||||
image: src.d3v.ac/xtcnet/d3v-server:latest
|
||||
container_name: d3v-npmwg
|
||||
restart: unless-stopped
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
|
|
@ -74,38 +66,26 @@ services:
|
|||
- net.ipv4.ip_forward=1
|
||||
- net.ipv4.conf.all.src_valid_mark=1
|
||||
ports:
|
||||
- "80:80" # HTTP
|
||||
- "81:81" # Admin UI
|
||||
- "443:443" # HTTPS
|
||||
- "51820-51830:51820-51830/udp" # WireGuard Multi-Server Range
|
||||
- "80:80"
|
||||
- "81:81"
|
||||
- "443:443"
|
||||
- "51820-51830:51820-51830/udp"
|
||||
volumes:
|
||||
- data:/data
|
||||
- letsencrypt:/etc/letsencrypt
|
||||
- wireguard:/etc/wireguard
|
||||
- ./data:/data
|
||||
- ./letsencrypt:/etc/letsencrypt
|
||||
- ./wireguard:/etc/wireguard
|
||||
environment:
|
||||
WG_HOST: "your.server.ip" # REQUIRED: Your server's public IP or domain
|
||||
# WG_PORT: 51820 # WireGuard listen port
|
||||
# WG_DEFAULT_ADDRESS: 10.8.0.0/24 # VPN subnet
|
||||
# WG_DNS: 1.1.1.1,8.8.8.8 # DNS for VPN clients
|
||||
# WG_MTU: 1420 # MTU for VPN
|
||||
# WG_ALLOWED_IPS: 0.0.0.0/0,::/0 # Allowed IPs for clients
|
||||
# WG_PERSISTENT_KEEPALIVE: 25
|
||||
# WG_ENABLED: true # Set to false to disable WireGuard
|
||||
|
||||
volumes:
|
||||
data:
|
||||
letsencrypt:
|
||||
wireguard:
|
||||
WG_HOST: "your.server.ip" # REQUIRED
|
||||
```
|
||||
|
||||
## 🔧 Environment Variables
|
||||
---
|
||||
|
||||
### WireGuard Settings
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `WG_ENABLED` | `true` | Enable/disable WireGuard VPN |
|
||||
| `WG_HOST` | *(required)* | Public IP or domain of your server |
|
||||
| `WG_ENABLED` | `true` | Enable/disable WireGuard |
|
||||
| `WG_PORT` | `51820` | WireGuard UDP listen port |
|
||||
| `WG_DEFAULT_ADDRESS` | `10.8.0.0/24` | VPN subnet CIDR |
|
||||
| `WG_DNS` | `1.1.1.1, 8.8.8.8` | DNS servers for VPN clients |
|
||||
|
|
@ -113,66 +93,45 @@ volumes:
|
|||
| `WG_ALLOWED_IPS` | `0.0.0.0/0, ::/0` | Default allowed IPs for clients |
|
||||
| `WG_PERSISTENT_KEEPALIVE` | `25` | Keepalive interval in seconds |
|
||||
|
||||
## 🌍 Ports
|
||||
## Ports
|
||||
|
||||
| Port | Protocol | Description |
|
||||
|------|----------|-------------|
|
||||
| `80` | TCP | HTTP |
|
||||
| `81` | TCP | Admin Web UI |
|
||||
| `443` | TCP | HTTPS |
|
||||
| `51820-51830` | UDP | WireGuard VPN Multi-Server Ports |
|
||||
| `51820–51830` | UDP | WireGuard Multi-Server |
|
||||
|
||||
## 📖 Usage
|
||||
---
|
||||
|
||||
1. **Access the Admin UI** at `http://your-server:81`
|
||||
2. **Set up NPM** with your admin email and password
|
||||
3. **Navigate to WireGuard** from the sidebar menu
|
||||
4. **Create VPN clients** by clicking "New Client"
|
||||
5. **Scan QR code** or **download .conf** file to configure WireGuard on your devices
|
||||
|
||||
## 🏗️ Building and CI/CD
|
||||
|
||||
### ☁️ Automated Build (Docker Cloud Build)
|
||||
This project is configured with **GitHub Actions** (`.github/workflows/docker-publish.yml`) to automatically build and push multi-arch Docker images (`amd64`, `arm64`) to **GitHub Container Registry (GHCR)** whenever a push is made to the `master` branch or a version tag is created.
|
||||
|
||||
Images are available at: `ghcr.io/xtcnet/d3v-npmwg:latest`
|
||||
|
||||
### 🏗️ Building from Source Local
|
||||
To build D3V-NPMWG from source manually, you must build the React frontend before building the Docker image:
|
||||
## Building from Source
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/xtcnet/D3V-NPMWG.git
|
||||
cd D3V-NPMWG
|
||||
git clone https://src.d3v.ac/xtcnet/D3V-Server.git
|
||||
cd D3V-Server
|
||||
|
||||
# 1. Build the Frontend
|
||||
cd frontend
|
||||
yarn install
|
||||
yarn build
|
||||
cd ..
|
||||
|
||||
# 2. Build the Docker Image
|
||||
# IMPORTANT: Do not forget the trailing dot '.' at the end of the command!
|
||||
docker build -t npm-wg -f docker/Dockerfile .
|
||||
cd frontend && yarn install && yarn locale-compile && yarn build && cd ..
|
||||
docker build -t d3v-npmwg -f docker/Dockerfile .
|
||||
```
|
||||
|
||||
Alternatively, you can run the helper script:
|
||||
```bash
|
||||
./scripts/build-project.sh
|
||||
```
|
||||
### CI/CD
|
||||
|
||||
## ⚠️ Requirements
|
||||
Pushes to `master` that touch `backend/`, `frontend/`, or `docker/` automatically build and push the Docker image to `src.d3v.ac/xtcnet/d3v-server:latest` via Forgejo Actions.
|
||||
|
||||
- **Docker** with Linux containers
|
||||
- **Host kernel** must support WireGuard (Linux 5.6+ or WireGuard kernel module)
|
||||
- Container requires `NET_ADMIN` and `SYS_MODULE` capabilities
|
||||
- IP forwarding must be enabled (`net.ipv4.ip_forward=1`)
|
||||
---
|
||||
|
||||
## 📜 Credits
|
||||
## Requirements
|
||||
|
||||
- Docker with Linux containers
|
||||
- Host kernel with WireGuard support (Linux 5.6+)
|
||||
- `NET_ADMIN` and `SYS_MODULE` capabilities
|
||||
- `net.ipv4.ip_forward=1`
|
||||
|
||||
## Credits
|
||||
|
||||
- [xGat3](https://github.com/NginxProxyManager/nginx-proxy-manager) — Original proxy manager
|
||||
- [wg-easy](https://github.com/wg-easy/wg-easy) — WireGuard management inspiration
|
||||
|
||||
## 📄 License
|
||||
## License
|
||||
|
||||
MIT License
|
||||
|
|
|
|||
Loading…
Reference in a new issue