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.
60 lines
2.1 KiB
Markdown
60 lines
2.1 KiB
Markdown
# 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.
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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`.
|