vpn/README.md

WireGuard VPN con wg-easy (Docker)

Una configurazione Docker pronta all'uso per eseguire un server VPN WireGuard con interfaccia web wg-easy, ideale per Raspberry Pi o qualsiasi server Linux.

---

Prerequisiti

• Docker e Docker Compose installati sul server
• Una porta UDP aperta sul router/firewall (default: 51820)
• Un indirizzo IP pubblico statico oppure un hostname DDNS (es. DuckDNS, No-IP)

---

Configurazione rapida

1. Clona il repository

git clone https://santantonio.sytes.net/davide/vpn.git
cd vpn

2. Crea il file .env

cp .env.example .env

L'unica variabile obbligatoria è TZ (già precompilata con Europe/Rome). Le porte possono essere lasciate ai valori di default.

Variabile	Descrizione	Default
TZ	Fuso orario (formato IANA)	Europe/Rome
WG_PORT	Porta UDP WireGuard	51820
WG_UI_PORT	Porta TCP interfaccia web	51821

Nota v15: host VPN, password e DNS si configurano dalla web UI al primo avvio.

3. Apri la porta sul router

Inoltra la porta UDP 51820 (o quella scelta in WG_PORT) verso l'IP locale del server.

4. Avvia il container

docker compose up -d

Al primo avvio, un init container crea automaticamente wg-data/ con permessi 700 prima che wg-easy scriva le chiavi private.

5. Completa il setup dalla web UI

http://IP_DEL_TUO_SERVER:51821

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.

---

Struttura del progetto

vpn/
├── docker-compose.yml   # Definizione del servizio
├── .env.example         # Template variabili (committato)
├── .env                 # Variabili locali (NON committato)
├── .gitignore
├── README.md
└── wg-data/             # Generato dal container al primo avvio (ignorato da git)
    ├── wg0.conf         # Configurazione WireGuard con chiavi private
    └── wg-easy.db       # Database interno wg-easy

---

Dispositivi a risorse limitate (SBC)

Su board con poca RAM (≤ 1 GB) il processo Node.js di wg-easy può crescere nel tempo e far sì che il kernel OOM-killi altri processi di sistema — SSH compreso. Per evitarlo, decommenta e adatta questi valori nel tuo .env:

# Board con 512 MB RAM
WG_MEM_LIMIT=96m
WG_MEMSWAP_LIMIT=96m

# Board con 1 GB RAM
WG_MEM_LIMIT=128m
WG_MEMSWAP_LIMIT=128m

Tieni WG_MEMSWAP_LIMIT uguale a WG_MEM_LIMIT per disabilitare lo swap del container: quando il container raggiunge il limite viene riavviato da Docker invece di consumare swap di sistema.

Assicurati anche che lo swap dell'host sia almeno 512 MB. Su Raspberry Pi OS il default è 100 MB — per aumentarlo:

sudo dphys-swapfile swapoff
sudo sed -i 's/CONF_SWAPSIZE=100/CONF_SWAPSIZE=512/' /etc/dphys-swapfile
sudo dphys-swapfile setup && sudo dphys-swapfile swapon

---

Aggiornare wg-easy

Esegui mensilmente per ricevere patch di sicurezza:

docker compose pull
docker compose up -d

---

Sicurezza

• wg-data/ contiene chiavi crittografiche private ed è completamente ignorata da git. I permessi 700 vengono impostati automaticamente dall'init container al primo avvio.
• .env contiene variabili locali specifiche del server. Non committarlo.