Premiers pas

Guide de déploiement

Passez de zéro à un panneau d'administration WireGuard VPN fonctionnel en moins de cinq minutes.

Prérequis

Un serveur Linux accessible depuis l’endroit où vous allez l’administrer
Docker et Docker Compose installés
Un nom de domaine pointant vers l’IP de votre serveur
Les ports 80 et 443 ouverts pour Caddy, ainsi que le port UDP de WireGuard ouvert (par défaut 51820)

Caddy nécessite un nom DNS valide, interne ou public, pointant vers votre serveur afin d'obtenir et de renouveler automatiquement les certificats SSL.

Déploiement

mkdir wireguard_webadmin && cd wireguard_webadmin

wget -O docker-compose.yml \
  https://raw.githubusercontent.com/eduardogsilva/wireguard_webadmin/main/docker-compose-caddy.yml

Créez un fichier .env dans le même répertoire. Définissez SERVER_ADDRESS avec votre domaine :

SERVER_ADDRESS=vpn.example.com
DEBUG_MODE=False
TIMEZONE=America/Sao_Paulo

Consultez la référence .env ci-dessous pour voir toutes les variables disponibles.

docker compose up -d

Accédez au panneau via https://vpn.example.com. Caddy obtient et renouvelle automatiquement les certificats SSL.

Référence .env

Variable	Obligatoire	Description
SERVER_ADDRESS	Oui	Nom DNS ou IP de votre serveur. Cela doit correspondre exactement à ce que vous saisissez dans le navigateur, sinon vous aurez des erreurs CSRF.
DEBUG_MODE	Non	Définissez `True` pour activer le mode debug de Django. Ne jamais l'utiliser en production. Valeur par défaut : `False`.
TIMEZONE	Non	Fuseau horaire de l'application. Utilisez une valeur issue de la base tz. Valeur par défaut : `America/Sao_Paulo`.
EXTRA_ALLOWED_HOSTS	Non	Noms d'hôte supplémentaires que Django doit accepter, séparés par des virgules. `SERVER_ADDRESS` est toujours inclus. Exemple : `app1.example.com,app2.example.com:8443`.
WIREGUARD_STATUS_CACHE_ENABLED	Non	Met en cache l'état de WireGuard afin de réduire les appels à `wg`. Valeur par défaut : `True`.
WIREGUARD_STATUS_CACHE_REFRESH_INTERVAL	Non	Fréquence de rafraîchissement du cache, en secondes. Valeurs autorisées : `30`, `60`, `150`, `300`. Valeur par défaut : `60`.
WIREGUARD_STATUS_CACHE_WEB_LOAD_PREVIOUS_COUNT	Non	Nombre d'instantanés en cache à précharger au chargement de la page (0-9). Des valeurs plus élevées préremplissent les graphiques de trafic. Réduisez-la si la liste des pairs semble lente. Valeur par défaut : `9`.
DISABLE_AUTO_APPLY	Non	Désactive l'application automatique des modifications de configuration WireGuard et DNS. Par défaut, les changements de pairs et de DNS sont appliqués immédiatement. Définissez sur `true` pour appliquer les modifications manuellement. Valeur par défaut : `false`.
WIREGUARD_MTU	Non	MTU personnalisé pour les interfaces WireGuard (serveur et clients). Ne modifiez que si vous savez ce que vous faites. Doit être un entier compris entre `1280` et `9000`. Après modification, réexportez et redistribuez tous les fichiers de configuration des clients — un MTU différent entre le serveur et les clients peut causer des problèmes de connectivité. Valeur par défaut : `1420`.
VPN_CLIENTS_CAN_ACCESS_DJANGO	Non	Permet aux clients VPN d'accéder directement à l'interface web via l'interface interne à l'adresse `http://ip_ou_hostname:8000`. Lorsqu'activé, l'adresse interne avec le port `:8000` doit être ajoutée à `EXTRA_ALLOWED_HOSTS`, sinon Django bloquera la requête. Valeur par défaut : `False`.

Mise à niveau

Les données sont conservées dans des volumes Docker. Une mise à niveau n'affecte ni vos pairs, ni vos règles de pare-feu, ni vos entrées DNS, ni aucune autre configuration.

Aller dans le répertoire du projet

cd wireguard_webadmin

Arrêter les services et récupérer les dernières images

docker compose down
docker compose pull

Sauvegarder vos données

tar cvfz wireguard-webadmin-backup-$(date +%Y-%m-%d-%H%M%S).tar.gz \
  /var/lib/docker/volumes/wireguard_webadmin_wireguard/_data/ \
  /var/lib/docker/volumes/wireguard_webadmin_rrd_data/_data/

Mettre à jour le fichier compose

wget -O docker-compose.yml \
  https://raw.githubusercontent.com/eduardogsilva/wireguard_webadmin/main/docker-compose-caddy.yml

Démarrer la stack mise à jour

docker compose up -d

Vérifier les logs pour repérer les erreurs inattendues

docker compose logs wireguard_webadmin

Dépannage

Caddy n’obtient pas de certificat

Vérifiez que l’enregistrement A de votre domaine pointe vers l’IP publique du serveur
Vérifiez que les ports 80 et 443 sont ouverts et non bloqués en amont
Consultez les logs de Caddy : docker compose logs caddy

Le panneau ne se charge pas

Vérifiez que tous les conteneurs sont en cours d’exécution : docker compose ps
Recherchez des erreurs : docker compose logs wireguard_webadmin
Vérifiez que SERVER_ADDRESS dans .env correspond exactement à ce que vous saisissez dans le navigateur

Erreurs CSRF à la connexion

SERVER_ADDRESS est mal configuré. Il doit correspondre au nom d’hôte, et au port si celui-ci n’est pas standard, utilisé pour accéder au panneau. Mettez .env à jour puis redémarrez avec docker compose up -d.

Les pairs WireGuard ne peuvent pas se connecter

Vérifiez que le port UDP de WireGuard est ouvert sur le pare-feu de l’hôte. La valeur par défaut est 51820, mais si vous exécutez plusieurs instances, chacune doit avoir son propre port.
Assurez-vous que la plage de ports UDP déclarée dans docker-compose.yml correspond à ce qui est configuré dans chaque instance WireGuard dans le panneau. En cas d’écart, le conteneur n’exposera pas le bon port sur l’hôte.
Vérifiez que le transfert IP est activé sur l’hôte : sysctl net.ipv4.ip_forward

Services en cours d’exécution

Service	Rôle
wireguard-webadmin	Application Django : interface web et API
caddy	Proxy inverse et TLS automatique
auth-gateway	Couche d'autorisation Zero Trust : impose des vérifications d'identité avant de transmettre vers l'upstream
cron	Tâches planifiées : activation/désactivation des pairs, rafraîchissement du cache
rrdtool	Historique du trafic : collecte de données RRD et génération de graphiques
dns	Résolveur basé sur dnsmasq avec prise en charge des listes de blocage par catégories