davide/vpn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(claude): document hardware compatibility and SBC constraints

Browse Source 
Add a dedicated section covering:
- tested architectures: arm64 (RPi 3/4/5, Orange Pi, Rock Pi), armv7,
  amd64 (x86_64 servers, VMs, Intel NUC)
- known ip6tables boot issue on hosts with BSP/minimal kernels and how
  wg-init solves it automatically across all architectures
- resource limit variables (WG_MEM_LIMIT, WG_MEMSWAP_LIMIT, WG_CPUS)
  with guidance for boards under 1 GB RAM

Also corrects stale wg0.json reference to wg-easy.db in constraints list.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Davide Grilli
2026-05-07 08:09:17 +02:00
parent df78675198
commit 19d03ea624
1 changed files with 28 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+28 -1
View File
@@ -37,8 +37,35 @@ docker compose logs -f wg-easy
## Important constraints
- `wg-data/` is auto-generated by the container on first start and holds live WireGuard keys (`wg0.conf`, `wg0.json`). Never commit it.
- `wg-data/` is auto-generated by the container on first start and holds live WireGuard keys (`wg0.conf`, `wg-easy.db`). Never commit it. Permissions are set to `700` automatically by `wg-init`.
- `.env` is gitignored.
- The container requires `NET_ADMIN` and `SYS_MODULE` capabilities plus `net.ipv4.ip_forward=1` sysctl — these are already set in `docker-compose.yml`.
- The router must forward UDP port 51820 (or `WG_PORT`) to the server's local IP.
- `INSECURE=true` is set in `docker-compose.yml` to allow HTTP access on the local network.
## SBC / resource-constrained devices
Works on any Linux host with a 64-bit kernel and WireGuard support. Tested architectures:
| Hardware | Arch | Notes |
|---|---|---|
| Raspberry Pi 5 | arm64 | kernel `6.12.x+rpt-rpi-2712` |
| Raspberry Pi 4 / 3B+ | arm64 / armv7 | 32-bit kernels need `armv7` image |
| Orange Pi, Rock Pi, Banana Pi | arm64 | depends on board BSP kernel |
| Generic x86\_64 server / VM | amd64 | standard Debian/Ubuntu/Fedora |
| Intel NUC / mini-PC | amd64 | same as above |
**Known issue — ip6tables modules not loaded at boot.**
Affects mostly SBC boards with custom BSP kernels, but can occur on any host where `ip6_tables` and `ip6table_nat` are not auto-loaded. Without them `wg-quick up wg0` fails and rolls back, leaving no `wg0` interface. Symptom: every API call returns `Command failed: wg show wg0 dump / No such device`.
The `wg-init` service handles this automatically: it runs `modprobe ip6_tables ip6table_nat` (with `SYS_MODULE` cap and `/lib/modules` bind-mounted read-only) before wg-easy starts. Failures are silenced (`|| true`) so the setup works on kernels where these modules are built-in or unavailable.
**Resource limits** (`docker-compose.yml`):
| Variable | Default | Purpose |
|---|---|---|
| `WG_MEM_LIMIT` | `256m` | Hard memory cap for wg-easy |
| `WG_MEMSWAP_LIMIT` | `256m` | Disables swap (swap = mem limit) |
| `WG_CPUS` | `1.0` | CPU share (1 core) |
Lower `WG_MEM_LIMIT` to `128m` on boards with less than 1 GB RAM. Do not set it below `96m` or the Node.js runtime will OOM-kill on startup.