384b95b81d
AGPL-3.0-or-later ensures copyleft applies even when WireGUI is run as a network service. README covers features, deployment, env vars, and our stance against enshittification.
106 lines
4.5 KiB
Markdown
106 lines
4.5 KiB
Markdown
# WireGUI
|
|
|
|
A self-hosted WireGuard VPN management platform built with Python, NiceGUI, and PostgreSQL.
|
|
|
|
WireGUI gives you a clean web interface for managing WireGuard peers, firewall rules, and user authentication -- without depending on any third-party cloud service. It's designed for teams and individuals who want full control over their VPN infrastructure.
|
|
|
|
## Against enshittification
|
|
|
|
This project exists because we believe infrastructure software should serve its users, not its investors. Too many open-source VPN tools have been enshittified -- features locked behind paid tiers, telemetry quietly added, self-hosting made deliberately painful to push you toward a managed offering.
|
|
|
|
WireGUI is AGPL-licensed specifically to prevent this. If you run it, you own it. If you modify it and offer it as a service, you share the source. No bait-and-switch, no open-core grift, no "community edition" that mysteriously lacks the features you actually need.
|
|
|
|
Software that manages your network traffic should be fully transparent and fully yours.
|
|
|
|
## Features
|
|
|
|
- **WireGuard management** -- create/delete peers, automatic IP allocation (IPv4 + IPv6), QR codes and `.conf` downloads
|
|
- **Firewall rules** -- per-user nftables chains with CIDR, protocol, and port range support
|
|
- **Multi-factor auth** -- TOTP authenticator apps and WebAuthn security keys
|
|
- **SSO** -- OpenID Connect and SAML identity providers with auto-provisioning
|
|
- **Magic links** -- passwordless email login
|
|
- **API tokens** -- programmatic access via REST API (`/api/v0`)
|
|
- **Dark/light theme** -- user preference stored in profile, auto mode follows system
|
|
- **VPN session management** -- configurable session duration with automatic peer expiry
|
|
- **Real-time stats** -- live RX/TX counters and handshake tracking
|
|
- **Diagnostics** -- WAN connectivity checks, peer status, system notifications
|
|
|
|
## Tech stack
|
|
|
|
| Layer | Technology |
|
|
|-------|-----------|
|
|
| UI | NiceGUI (reactive server-side, WebSocket) |
|
|
| API | FastAPI (built into NiceGUI) |
|
|
| ORM | SQLModel (SQLAlchemy + Pydantic) |
|
|
| Database | PostgreSQL (asyncpg) |
|
|
| Cache | Valkey (Redis-compatible) |
|
|
| Migrations | Alembic |
|
|
| Auth | authlib, python-jose, pyotp, webauthn, bcrypt |
|
|
| VPN | WireGuard (`wg` + `ip` CLI) |
|
|
| Firewall | nftables (`nft` CLI) |
|
|
| Python | 3.13+ |
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# Clone and install
|
|
git clone https://forge.provvedo.com/provvedo/wiregui.git
|
|
cd wiregui
|
|
uv sync
|
|
|
|
# Start PostgreSQL and Valkey
|
|
docker compose up -d
|
|
|
|
# Run migrations and start
|
|
alembic upgrade head
|
|
uv run python -m wiregui.main
|
|
```
|
|
|
|
Open http://localhost:13000 -- an admin account is created automatically on first run (check the logs for the generated password).
|
|
|
|
## Production deployment
|
|
|
|
```bash
|
|
# Docker Compose (recommended)
|
|
docker compose -f compose.prod.yml up -d
|
|
```
|
|
|
|
The container runs migrations on startup, manages the WireGuard interface, and requires `NET_ADMIN` + `SYS_MODULE` capabilities. See `compose.prod.yml` for the full configuration including environment variables.
|
|
|
|
### Environment variables
|
|
|
|
All settings use the `WG_` prefix:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `WG_DATABASE_URL` | `postgresql+asyncpg://wiregui:wiregui@localhost/wiregui` | PostgreSQL connection |
|
|
| `WG_REDIS_URL` | `redis://localhost:6379/0` | Valkey/Redis connection |
|
|
| `WG_SECRET_KEY` | `change-me-in-production` | JWT signing + Fernet encryption key |
|
|
| `WG_WG_ENABLED` | `false` | Enable WireGuard interface management |
|
|
| `WG_WG_ENDPOINT_HOST` | `localhost` | Public endpoint for client configs |
|
|
| `WG_WG_ENDPOINT_PORT` | `51820` | WireGuard listen port |
|
|
| `WG_WG_IPV4_NETWORK` | `10.3.2.0/24` | IPv4 tunnel network |
|
|
| `WG_WG_IPV6_NETWORK` | `fd00::3:2:0/120` | IPv6 tunnel network |
|
|
| `WG_ADMIN_EMAIL` | `admin@localhost` | Initial admin email |
|
|
| `WG_ADMIN_PASSWORD` | *(auto-generated)* | Initial admin password |
|
|
| `WG_EXTERNAL_URL` | `http://localhost:13000` | Public-facing URL |
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Unit + integration tests
|
|
uv run pytest tests/ --ignore=tests/e2e -v
|
|
|
|
# E2E tests (NiceGUI User fixture)
|
|
uv run pytest tests/e2e/ -v
|
|
```
|
|
|
|
## License
|
|
|
|
Copyright 2026 Stefano Bertelli / Provvedo
|
|
|
|
This program is free software: you can redistribute it and/or modify it under the terms of the **GNU Affero General Public License** as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
|
|
|
|
This means: if you run a modified version of WireGUI as a network service, you must make the source code available to users of that service. No exceptions, no loopholes.
|
|
|
|
See [LICENSE](LICENSE) for the full text.
|