chore: add AGPL-3.0 license and README
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.
This commit is contained in:
Stefano Bertelli
parent
3747b963cb
commit
384b95b81d
4 changed files with 770 additions and 1 deletions
106
README.md
106
README.md
|
|
@ -0,0 +1,106 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue