jcoffey
6c006e1d4d
Go backend that drives kernel WireGuard over netlink (wireguard-go as the fallback), nftables NAT with MSS clamping, forwarding and buffer sysctls, SQLite for peers, users, sessions, traffic history and the audit log. React console: dashboard with live rates and usage history, peer management with QR codes and .conf downloads, disconnect, session reset, key rotation, expiry, client-supplied keys, settings, users with admin and viewer roles, two-factor authentication with recovery codes, audit log. Docker image on Alpine with compose files for bridged and host networking, CI and GHCR publish workflows, performance notes.
2.1 KiB
2.1 KiB
Contributing to WGX
Thanks for your interest. Bug reports, feature requests, code and documentation are all welcome.
Before you start
- WGX is one container: the WireGuard server and the UI that manages it. Contributions that need a second service (a database, a message queue, a separate frontend host) are out of scope.
- The kernel data plane is the point. Anything on the packet path has to justify its cost.
- This project is licensed under AGPL-3.0. Code you contribute is distributed under that licence, including for hosted deployments.
Development
You need Go (see go.mod for the version), Node 26 and Docker.
# Frontend, with hot reload, proxying /api to a local server on :51821
cd web && npm ci && npm run dev
# Backend against the in-memory mock data plane -- no privileges needed
WGX_BACKEND=mock WGX_DATA_DIR=/tmp/wgx WGX_HTTP_LISTEN=127.0.0.1:51821 go run ./cmd/wgx
The mock simulates peers handshaking and moving traffic so the dashboard has something to show. For the real thing:
cd web && npm run build && cd ..
docker build -t wgx:dev .
docker run --rm --cap-add NET_ADMIN --sysctl net.ipv4.ip_forward=1 \
-p 51820:51820/udp -p 127.0.0.1:51821:51821 -v wgx-dev:/data wgx:dev
Before you commit
CI checks are not a substitute for building locally. Run, in this order:
cd web && npm run build && cd .. # type-checks and builds the UI
go vet ./... && go test -count=1 ./...
docker build -t wgx:dev . # when the change reaches the image
go test covers the engine against the mock data plane and the whole HTTP
API through httptest. A change to the data plane itself (internal/wg,
internal/netcfg) needs a run in a container with NET_ADMIN and a real
client handshake; say in the pull request that you did that.
Pull requests
- One change per pull request, with a description of what and why.
- Keep the commit message about the change. No tooling attributions or generated-by footers.
- New settings need a line in the README's configuration table; anything on
the packet path needs a note in
docs/performance.md.