From e17730086469485702d4f70f05c4428e54882398 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Mon, 4 May 2026 23:58:36 +0200 Subject: [PATCH] docs: aggiorna documentazione per wg-easy v15 Rimuove le istruzioni per generare PASSWORD_HASH, aggiorna la tabella variabili, descrive il wizard di setup al primo avvio e aggiunge la raccomandazione di aggiornamento mensile per la sicurezza. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 17 +++++++---------- README.md | 57 ++++++++++++++++--------------------------------------- 2 files changed, 23 insertions(+), 51 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 88f472b..d978820 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,10 +11,7 @@ A Docker Compose setup for a self-hosted WireGuard VPN server using [wg-easy](ht ```bash # First-time setup cp .env.example .env -# Edit .env with WG_HOST, PASSWORD_HASH, TZ - -# Generate bcrypt password hash (no extra dependencies) -docker run --rm -it ghcr.io/wg-easy/wg-easy wgpw 'YourPassword' +# Edit .env: set TZ, optionally WG_PORT / WG_UI_PORT # Start the VPN docker compose up -d @@ -28,20 +25,20 @@ docker compose logs -f wg-easy ## Configuration -All runtime configuration lives in `.env` (not committed). Required variables: +`.env` (not committed) controls only infrastructure-level settings: | Variable | Description | |---|---| -| `WG_HOST` | Public IP or DDNS hostname clients connect to | -| `PASSWORD_HASH` | bcrypt hash of the web UI password (prefix `$2a$`, `$2b$`, or `$2y$`) | | `TZ` | IANA timezone (e.g. `Europe/Rome`) | +| `WG_PORT` | UDP VPN port (default 51820) | +| `WG_UI_PORT` | Web UI port (default 51821) | -Optional: `WG_PORT` (default 51820/udp), `WG_UI_PORT` (default 51821/tcp), `WG_DEFAULT_DNS` (default `1.1.1.1,8.8.8.8`). +**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 — it holds the password hash and hostname. +- `.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. -- `openssl passwd` does **not** support bcrypt — use the Docker method, `htpasswd`, or Python's `bcrypt` library to generate `PASSWORD_HASH`. +- `INSECURE=true` is set in `docker-compose.yml` to allow HTTP access on the local network. diff --git a/README.md b/README.md index 4e3ce2c..026fba9 100644 --- a/README.md +++ b/README.md @@ -27,60 +27,33 @@ cd vpn cp .env.example .env ``` -Apri `.env` con un editor e compila i valori richiesti: +L'unica variabile obbligatoria è `TZ` (già precompilata con `Europe/Rome`). Le porte possono essere lasciate ai valori di default. -| Variabile | Descrizione | Obbligatoria | +| Variabile | Descrizione | Default | |---|---|---| -| `WG_HOST` | IP pubblico o hostname DDNS del server | Sì | -| `PASSWORD_HASH` | Hash della password per la UI web (vedi sotto) | Sì | -| `TZ` | Fuso orario (formato IANA, es. `Europe/Rome`) | Sì | -| `WG_PORT` | Porta UDP WireGuard (default: `51820`) | No | -| `WG_UI_PORT` | Porta TCP interfaccia web (default: `51821`) | No | -| `WG_DEFAULT_DNS` | DNS inviati ai client (default: `1.1.1.1,8.8.8.8`) | No | +| `TZ` | Fuso orario (formato IANA) | `Europe/Rome` | +| `WG_PORT` | Porta UDP WireGuard | `51820` | +| `WG_UI_PORT` | Porta TCP interfaccia web | `51821` | -### 3. Genera e imposta la password +> **Nota v15:** host VPN, password e DNS si configurano dalla web UI al primo avvio. -La password non si scrive in chiaro nel file `.env`: va convertita in un **hash** (una stringa cifrata che wg-easy usa per verificare il login senza conservare la password originale). - -**Passo 1** — Scegli la password che vuoi usare per accedere all'interfaccia web, poi esegui questo comando sostituendo `LatuaPassword` con quella scelta: - -```bash -docker run --rm -it ghcr.io/wg-easy/wg-easy wgpw 'LatuaPassword' -``` - -**Passo 2** — Il comando stampa una riga simile a questa: - -``` -PASSWORD_HASH='$2a$12$cDMCiMmFTuMOlT1E4BvxEO4CJfzMKSanRZSMqiE1234abcXYZ' -``` - -**Passo 3** — Copia solo la parte dopo `PASSWORD_HASH=`, **senza** le virgolette singole. Nel file `.env` deve apparire così: - -``` -PASSWORD_HASH=$2a$12$cDMCiMmFTuMOlT1E4BvxEO4CJfzMKSanRZSMqiE1234abcXYZ -``` - -> **Attenzione:** non aggiungere virgolette, spazi o altri caratteri intorno al valore. Copia e incolla esattamente quello che hai ottenuto. - -### 4. Apri la porta sul router +### 3. Apri la porta sul router Inoltra la porta **UDP 51820** (o quella scelta in `WG_PORT`) verso l'IP locale del server. -### 5. Avvia il container +### 4. Avvia il container ```bash docker compose up -d ``` -Al primo avvio la directory `wg-data/` viene creata automaticamente con tutte le chiavi crittografiche. Non è necessario modificarla manualmente. - -### 6. Accedi all'interfaccia web +### 5. Completa il setup dalla web UI ``` http://IP_DEL_TUO_SERVER:51821 ``` -Da qui puoi aggiungere client, scaricare i file di configurazione e generare QR code per dispositivi mobili. +Al primo avvio appare un wizard che guida nella configurazione di password, hostname DDNS e DNS per i client. Dopo il setup puoi aggiungere client, scaricare configurazioni e generare QR code per dispositivi mobili. --- @@ -90,18 +63,20 @@ Da qui puoi aggiungere client, scaricare i file di configurazione e generare QR vpn/ ├── docker-compose.yml # Definizione del servizio ├── .env.example # Template variabili (committato) -├── .env # Variabili locali con segreti (NON committato) +├── .env # Variabili locali (NON committato) ├── .gitignore ├── README.md └── wg-data/ # Generato automaticamente dal container (NON committato) - ├── wg0.conf # Configurazione WireGuard (chiavi reali) - └── wg0.json # Stato interno wg-easy (chiavi reali) + ├── wg0.conf # Configurazione WireGuard + └── wg0.json # Stato interno wg-easy (peer, chiavi) ``` --- ## Aggiornare wg-easy +Esegui mensilmente per ricevere patch di sicurezza: + ```bash docker compose pull docker compose up -d @@ -112,5 +87,5 @@ docker compose up -d ## Sicurezza - `wg-data/` contiene chiavi crittografiche private. Non committarla mai su Git. -- `.env` contiene la password (hash) e il tuo hostname. Non committarlo. +- `.env` contiene variabili locali specifiche del server. Non committarlo. - Entrambi sono esclusi da `.gitignore`.