vpn/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

A Docker Compose setup for a self-hosted WireGuard VPN server using [wg-easy](https://github.com/wg-easy/wg-easy), designed to run on a Raspberry Pi or any Linux server. The web UI (wg-easy) handles client management, QR code generation, and key lifecycle.

## Common commands

```bash
# First-time setup
cp .env.example .env
# Edit .env: set TZ, optionally WG_PORT / WG_UI_PORT

# Start the VPN
docker compose up -d

# Update wg-easy to the latest image
docker compose pull && docker compose up -d

# View logs
docker compose logs -f wg-easy
```

## Configuration

`.env` (not committed) controls only infrastructure-level settings:

| Variable | Description |
|---|---|
| `TZ` | IANA timezone (e.g. `Europe/Rome`) |
| `WG_PORT` | UDP VPN port (default 51820) |
| `WG_UI_PORT` | Web UI port (default 51821) |

**v15+:** Host, password, and DNS are configured through the web UI wizard on first launch — not via environment variables.

## 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.
- `.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.