WireGuard Port Forwarding Platform (MVP)

A self-hosted platform for managing dynamic port forwarding through WireGuard tunnels. Clients connect via WireGuard VPN and can expose local services through the server's public IP.

🎯 Features

• WireGuard-based tunneling - Secure, modern VPN protocol
• Dynamic port mapping - Map public ports to client services (TCP/UDP)
• Web Admin UI - React-based dashboard for management
• REST API - Full-featured API with JWT authentication
• Role-based access - Admin and user roles with proper isolation
• Real-time config updates - Nginx stream proxy with automatic reloading
• Multi-architecture - Supports linux/amd64, linux/arm64, and Windows agents

🏗️ Architecture

┌─────────┐      ┌────────────┐      ┌──────────────┐
│ Admin   │─────▶│   Caddy    │─────▶│  FastAPI     │
│ UI      │      │  (Port 83) │      │  (Port 8080) │
└─────────┘      └────────────┘      └──────────────┘
                                              │
                                              ▼
                 ┌────────────┐      ┌──────────────┐
                 │ Controller │◀─────│  PostgreSQL  │
                 │  (Config)  │      │   Database   │
                 └────────────┘      └──────────────┘
                        │
                        ▼
                 ┌────────────┐      ┌──────────────┐
   Internet      │   Nginx    │◀────▶│  WireGuard   │
   Traffic ─────▶│   Stream   │      │    Server    │
                 │ (20000-    │      │  (51820/udp) │
                 │  20100)    │      └──────────────┘
                 └────────────┘              ▲
                                             │
                                             │ WG Tunnel
                                             ▼
                                      ┌──────────────┐
                                      │    Agent     │
                                      │   (Client)   │
                                      └──────────────┘
                                             │
                                             ▼
                                      [Local Services]

🚀 Quick Start

📌 For Production Deployment: See QUICKSTART_PRODUCTION.md for VPS deployment with Traefik + Windows agent

Local Development

Prerequisites

• Docker & Docker Compose
• Linux host (for server components)
• Supported architectures: linux/amd64, linux/arm64
• Ports available: 83 (UI), 51820 (WireGuard), 20000-20100 (forwarding)

For Windows agents: See WINDOWS_SETUP.md for client setup

1. Clone and Configure

git clone <repo>
cd wg-gaming-tunnel

# Copy environment template
cp .env.example .env

# Edit credentials (required)
nano .env
# Set ADMIN_EMAIL and ADMIN_PASSWORD
# Optionally change JWT_SECRET

2. Build and Start

# Build all services
make build

# Start stack
make up

# Or manually:
docker compose up -d

3. Access Admin UI

Open http://localhost:83 and login with credentials from .env:

• Email: admin@example.com (or your custom value)
• Password: admin123 (or your custom value)

4. Verify Services

# Check all services are running
docker compose ps

# View logs
docker compose logs -f

# Run skeleton tests
make test

📖 Usage

Creating a Client

1. In Admin UI:

   • Navigate to Dashboard
   • Click "New Client"
   • Enter client name
   • Click "Create"

2. Set WireGuard Key:

   • Generate client key pair:

     wg genkey | tee client_private.key | wg pubkey > client_public.key
     

   • In UI, click "Set Key" for the client
   • Paste contents of client_public.key
   • System assigns WireGuard IP automatically (e.g., 10.10.0.3)

3. Note assigned IP - You'll need this for WireGuard client config

Creating Port Mappings

1. In Admin UI, go to "Mappings" section
2. Click "New Mapping"
3. Select client
4. Choose protocol (TCP/UDP)
5. Set public port (20000-20100)
6. Set target port (port on client machine)
7. Click "Create"

Mapping propagates to Nginx within ~2 seconds.

Connecting a Client (Manual)

Note: Agent implementation is pending. For now, manual WireGuard setup:

1. Create WireGuard config on client:

[Interface]
PrivateKey = <contents of client_private.key>
Address = <assigned IP from UI>/24
DNS = 1.1.1.1

[Peer]
PublicKey = <server public key - see below>
Endpoint = <server IP>:51820
AllowedIPs = 10.10.0.0/24
PersistentKeepalive = 25

2. Get server public key:

docker compose exec wireguard cat /etc/wireguard/server_public.key

3. Start WireGuard on client:

wg-quick up wg0

4. IMPORTANT: Manually add peer to server (until agent is implemented):

docker compose exec wireguard wg set wg0 peer <CLIENT_PUBKEY> allowed-ips <CLIENT_IP>/32

🛠️ Development

Project Structure

wg-gaming-tunnel/
├── db/                    # Database initialization
│   └── init.sql          # Schema, indexes, constraints
├── docs/                  # Documentation
│   ├── ARCHITECTURE.md   # System design
│   └── SECURITY.md       # Security considerations
├── infra/                 # Infrastructure services
│   ├── caddy/            # Reverse proxy
│   ├── nginx-stream/     # TCP/UDP proxy
│   │   ├── controller/   # Config generator
│   │   └── templates/    # Nginx config templates
│   └── wireguard-server/ # WireGuard userspace
├── services/              # Application services
│   ├── agent/            # Client agent (Go) [INCOMPLETE]
│   ├── api/              # FastAPI backend
│   │   └── app/
│   │       ├── routers/  # API endpoints
│   │       ├── models.py # SQLAlchemy models
│   │       └── schemas.py# Pydantic schemas
│   └── ui/               # React admin UI
│       └── src/
│           ├── components/
│           ├── api.js    # API client
│           └── App.jsx
├── tests/                 # E2E tests
└── docker-compose.yml    # Service orchestration

API Endpoints

Authentication:

• POST /auth/login - Get JWT tokens

Clients:

• GET /clients - List own clients
• POST /clients - Create client
• POST /clients/{id}/keys - Set WireGuard public key

Mappings:

• GET /mappings - List own mappings
• POST /mappings - Create mapping
• PATCH /mappings/{id} - Enable/disable
• DELETE /mappings/{id} - Delete mapping

Running Tests

# Skeleton tests (health checks)
make test

# Manual API test
TOKEN=$(curl -s -X POST http://localhost:83/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"admin123"}' | jq -r '.access_token')

curl -H "Authorization: Bearer $TOKEN" http://localhost:83/api/clients

Database Access

# Connect to database
docker compose exec db psql -U app -d app

# Check tables
docker compose exec db psql -U app -d app -c "\dt"

# View clients
docker compose exec db psql -U app -d app -c "SELECT * FROM clients;"

⚙️ Configuration

Environment Variables

See .env.example for all options. Key variables:

Variable	Default	Description
ADMIN_EMAIL	-	Admin user email (required)
ADMIN_PASSWORD	-	Admin user password (required)
JWT_SECRET	changeme	JWT signing secret (change in prod!)
JWT_EXP_MINUTES	60	Access token expiration
WG_SUBNET	10.10.0.0/24	WireGuard VPN subnet
WG_PORT	51820	WireGuard UDP port

Ports

Service	Internal	External	Protocol
Caddy (UI)	80	83	HTTP
Caddy (HTTPS)	443	448	HTTPS
API	8080	-	HTTP (internal)
WireGuard	51820	51820	UDP
Nginx Stream	20000-20100	20000-20100	TCP/UDP

📝 TODO / Known Issues

See PROJECT_AUDIT.md for comprehensive status.

Critical Missing:

• ✅ API implementation - DONE
• ✅ Admin UI - DONE
• ⚠️ WireGuard peer management (no automatic peer addition)
• ⚠️ Agent implementation (placeholder only)
• ⚠️ Full E2E tests (skeleton only)

Next Steps:

1. Implement WireGuard peer management in controller
2. Complete agent (WG setup, registration, keepalive)
3. Write full E2E tests with traffic validation

🔒 Security

• JWT-based authentication with bcrypt password hashing
• Role-based access control (admin vs user)
• WireGuard for encrypted tunnels
• PostgreSQL for data persistence with proper constraints
• No secrets in git (use .env for credentials)

Production Considerations:

• Change default JWT_SECRET
• Use strong admin password
• Enable TLS in Caddy
• Add rate limiting
• Run services as non-root
• Regular security updates

🏗️ Multi-Architecture Support

This project supports multiple platforms:

Server Components (linux/amd64, linux/arm64):

• Raspberry Pi 4/5, AWS Graviton, Apple Silicon
• Standard x86_64 servers

Agent (linux/amd64, linux/arm64, windows/amd64, windows/arm64):

• Works on any platform including Windows desktops/laptops

Build Multi-Arch Images

# Build for all architectures
./build-multiarch.sh

# Build Windows agent binary
./build-windows-agent.sh amd64

See MULTIARCH.md for detailed instructions.

📚 Documentation

Production Deployment

• QUICKSTART_PRODUCTION.md - 10-minute deployment guide (VPS + Windows)
• DEPLOY.md - Complete production deployment guide
• WINDOWS_SETUP.md - Windows agent setup guide

Development & Architecture

• docs/ARCHITECTURE.md - System design and data flow
• docs/SECURITY.md - Security model and threat analysis
• MULTIARCH.md - Multi-architecture deployment guide
• GITEA_SETUP.md - Gitea repository and CI/CD setup
• GITEA_QUICKSTART.md - Quick Gitea setup guide
• TODO.md - Development backlog
• PROJECT_AUDIT.md - Current status and issues

🤝 Contributing

1. Check TODO.md for open tasks
2. Follow existing code style
3. Add tests for new features
4. Update documentation

📄 License

[Add your license]

🙋 Support

For issues or questions, see documentation in docs/ or review PROJECT_AUDIT.md for known issues.