wg-easy v15 (2026) : installation Docker Compose et panneau verrouillé

wg-easy est une image Docker gratuite qui fait tourner WireGuard avec un panneau d'administration web sur votre propre serveur : on ajoute les appareils, on télécharge leurs configs et on affiche les QR codes depuis le navigateur au lieu d'éditer wg0.conf. La version 15 est l'actuelle ; il lui faut un VPS avec le port UDP 51820 ouvert.

WireGuard est rapide et moderne, mais l'installation standard, ce sont des fichiers et la ligne de commande : générer des clés, éditer wg0.conf à la main, lancer wg set pour chaque appareil, faire circuler les configs. Pour un appareil, ça va. Pour une famille, quelques ordinateurs et deux téléphones, ça devient pénible - et c'est dans le pénible que les erreurs (et les clés qui fuitent) surviennent. wg-easy résout exactement ça : il garde le vrai WireGuard en dessous, intact, et y greffe un tableau de bord web propre. Ajouter un client en deux clics, afficher un QR code pour un téléphone, voir qui est connecté et combien il transfère. Voici l'installation complète 2026, y compris le changement de mot de passe qui piège tous ceux qui mettent à jour.

Ce qu'il vous faut : un VPS Linux avec une adresse IPv4 publique et Docker, avec le port UDP 51820 ouvert. Ce guide prend un Cloud VPS Contabo comme exemple d'hôte ; les prérequis sont détaillés plus bas.

Vous n'avez pas encore choisi le serveur ? Notre classement des VPS les moins chers pour WireGuard compare ce que chaque hébergeur facture vraiment pour un serveur utilisable.

Astuce : si le tunnel refuse de se connecter, la cause est presque toujours le port. Voir notre guide sur le port par défaut de WireGuard (UDP 51820) et comment l'ouvrir, le rediriger ou le changer.

Sans copier-coller : le générateur docker-compose wg-easy, gratuit, écrit le docker-compose.yml de la v15 adapté à votre installation, dans le navigateur : panneau d'administration sur localhost seulement ou en HTTPS sur votre propre domaine via Caddy, et premier démarrage sans assistant en option.

# wg-easy v15 - generated on vpnsmith.com/en/tools/wg-easy-compose-generator
# Host: vpn.example.com - WireGuard port: 51820/udp - panel: https://wg.example.com

volumes:
  etc_wireguard:
  caddy_data:
  caddy_config:

services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    environment:
      - PORT=80
      - TRUSTED_PROXIES=10.42.42.43,fdcc:ad94:bacf:61a3::2b
    networks:
      wg:
        ipv4_address: 10.42.42.42
        ipv6_address: fdcc:ad94:bacf:61a3::2a
    volumes:
      - etc_wireguard:/etc/wireguard
      - /lib/modules:/lib/modules:ro
    ports:
      - "51820:51820/udp"   # WireGuard: the only port clients need
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
      - net.ipv6.conf.default.forwarding=1

  caddy:
    image: caddy:2-alpine
    container_name: caddy
    ports:
      - "80:80/tcp"
      - "443:443/tcp"
      - "443:443/udp"
    networks:
      wg:
        ipv4_address: 10.42.42.43
        ipv6_address: fdcc:ad94:bacf:61a3::2b
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    restart: unless-stopped

networks:
  wg:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 10.42.42.0/24
        - subnet: fdcc:ad94:bacf:61a3::/64

wg.example.com {
	reverse_proxy wg-easy:80
}

# 1. Pare-feu : SSH d'abord, puis le port WireGuard
sudo ufw allow OpenSSH
sudo ufw allow 51820/udp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw enable
# Attention : les ports publiés par Docker contournent ufw. Ouvrez/fermez-les aussi dans le pare-feu de l'hébergeur.

# 2. Créez le dossier et collez le ou les fichiers générés
sudo mkdir -p /etc/docker/containers/wg-easy
cd /etc/docker/containers/wg-easy
sudo nano docker-compose.yml
sudo nano Caddyfile

# 3. Démarrez wg-easy
sudo docker compose up -d
# Suivez les journaux (Ctrl+C pour quitter)
sudo docker compose logs -f wg-easy

# 4. Ouvrez le panneau: https://wg.example.com

Ce qu'est wg-easy (et ce qu'il n'est pas)

wg-easy est un unique conteneur Docker qui fait tourner un serveur WireGuard et une petite application web pour le gérer. Le point clé à comprendre d'emblée : il ne remplace ni ne réimplémente WireGuard. Le tunnel reste le même WireGuard du noyau, avec les mêmes clés et le même protocole sur le fil. wg-easy, c'est de la gestion, pas un nouveau VPN. Deux conséquences :

• Aucune perte de vitesse. Le débit et la latence sont identiques à une config écrite à la main, car le chemin des données ne touche jamais l'application web.
• L'interface web est la surface d'attaque. Le tableau de bord peut créer des clients : qui le contrôle contrôle votre VPN. Protéger ce panneau, c'est toute l'histoire de la sécurité (voir plus bas).

Ce que vous y gagnez : une page navigateur listant chaque client, créer/désactiver/supprimer en un clic, un QR code par client pour les téléphones, et un compteur de transfert en direct par peer. Pour intégrer une poignée d'appareils sans toucher au terminal, rien n'est plus rapide.

Avant de commencer : l'hôte qu'il vous faut

wg-easy est un conteneur, il vous faut donc un hôte Linux capable de faire tourner Docker et disposant d'une IP publique. Pour un VPN joignable de partout, cela signifie un petit VPS - WireGuard est si léger qu'une instance à 4-6 €/mois sature son port réseau bien avant que le CPU ne s'en aperçoive. Contabo sert ici d'exemple pour son rapport prix/bande passante, et la procédure bare-metal est dans notre guide WireGuard auto-hébergé sur Contabo si vous voulez comparer avec la voie manuelle.

Prends un VPS Contabo pour faire tourner wg-easy →

Seconde option si vous préférez un délai de remboursement de 30 jours : le VPS Basic d'Ultahost, lu sur ultahost.com le 21 octobre 2026 à 5,52 $ par mois facturés sur 24 mois (prix barré 9,19 $), avec 1 cœur CPU, 1 Go de DDR5, 30 Go de NVMe, une IPv4 dédiée et une garantie satisfait ou remboursé de 30 jours. 1 Go suffit pour Docker et le conteneur wg-easy sur un VPN personnel. L'offre ne publie ni débit de port ni volume de trafic, vérifiez-les avant de compter dessus pour un usage intensif.

Sur l'hôte, il vous faut Docker et le plugin Compose installés, le module noyau WireGuard disponible (toute distro moderne, Linux 5.6+, le livre), et la possibilité d'ouvrir l'UDP 51820 dans à la fois le pare-feu de l'hôte et le groupe de sécurité de votre fournisseur.

Le fichier docker-compose (wg-easy v15)

Vérification de version (24 octobre 2026) : la version actuelle est la v15.5.0 (24 octobre 2026). La v15 est une réécriture complète : WG_HOST, PASSWORD_HASH et la plupart des autres variables de la v14 ont disparu, leurs réglages se font désormais dans l'interface web. Un tutoriel v14 collé sur l'image :latest lance un conteneur qui ignore sans prévenir votre hôte et votre mot de passe. Tout ce qui suit est la méthode v15, tirée du fichier compose et de la documentation du projet.

La v15.5.0 en une minute : elle embarque les correctifs de sécurité Node.js d'octobre 2026, donc mettez à jour même si tout marche : sudo docker compose pull && sudo docker compose up -d (l'étiquette :15 utilisée plus bas suit la nouvelle version, vos clients et vos clés restent dans le volume). Elle passe aussi sa prise en charge intégrée d'AmneziaWG en version 3.1, ajoute WG_INTERFACE (par défaut wg0) pour faire tourner deux instances sur un même hôte, et TRUSTED_PROXIES pour un panneau derrière un reverse proxy (voir la section sur le verrouillage). Source : notes de version v15.5.0 et documentation de configuration optionnelle du projet.

Ce fichier reprend le fichier officiel, avec un changement volontaire : l'interface web n'est publiée que sur 127.0.0.1, le panneau d'admin n'est donc jamais joignable depuis Internet et vous l'ouvrez par un tunnel SSH. Vous voulez un panneau en HTTPS sur votre propre domaine via Caddy, ou un premier démarrage entièrement automatique ? Notre générateur docker-compose wg-easy écrit cette variante pour vous.

services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    environment:
      - INSECURE=true   # panel over plain HTTP, reached only through an SSH tunnel
    networks:
      wg:
        ipv4_address: 10.42.42.42
        ipv6_address: fdcc:ad94:bacf:61a3::2a
    volumes:
      - etc_wireguard:/etc/wireguard
      - /lib/modules:/lib/modules:ro
    ports:
      - "51820:51820/udp"             # WireGuard data: open to the internet
      - "127.0.0.1:51821:51821/tcp"   # web UI: bound to localhost only
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
      - net.ipv6.conf.default.forwarding=1

networks:
  wg:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 10.42.42.0/24
        - subnet: fdcc:ad94:bacf:61a3::/64

volumes:
  etc_wireguard:

Ce que fait chaque partie, et là où ça casse d'habitude :

• 127.0.0.1:51821:51821/tcp garde le panneau hors de l'interface publique. C'est plus important qu'il n'y paraît : les ports publiés par Docker contournent UFW, donc un simple "51821:51821/tcp" est ouvert au monde même si ufw status dit le contraire.
• INSECURE=true est nécessaire parce que le panneau est servi ici en HTTP simple (le chiffrement, c'est le tunnel SSH). Sans lui, la v15 marque son cookie de connexion Secure, le navigateur l'ignore en HTTP, et vous revenez sur la page de connexion à chaque essai.
• cap_add: NET_ADMIN et sysctls: net.ipv4.ip_forward=1 permettent au conteneur de créer l'interface WireGuard et de router pour vos clients. Sans l'un ou l'autre, le tunnel se connecte puis ne route rien.
• Le volume nommé etc_wireguard contient la base avec toutes les clés et tous les clients : un docker compose down suivi d'un up conserve vos appareils.

Mettez-le en place et démarrez-le, avec l'arborescence de la documentation officielle :

sudo mkdir -p /etc/docker/containers/wg-easy
cd /etc/docker/containers/wg-easy
sudo nano docker-compose.yml   # paste the file above
sudo docker compose up -d
sudo docker compose logs -f wg-easy   # Ctrl+C once it is listening

Puis ouvrez le panneau depuis votre propre machine, à travers le tunnel :

# on your own computer, not on the server
ssh -L 51821:127.0.0.1:51821 user@YOUR_SERVER_IP
# then open http://localhost:51821 in your browser

Premier démarrage : l'assistant de configuration (fini PASSWORD_HASH)

Le PASSWORD_HASH bcrypt et la commande wgpw, auxquels chaque tutoriel v14 consacre une section, n'existent plus. À la première visite, la v15 ouvre un assistant :

1. Créer le compte admin : un nom d'utilisateur et un mot de passe. wg-easy stocke lui-même le mot de passe sous forme de hash argon2, il n'y a donc rien à générer ni à échapper dans un fichier .env.
2. « Avez-vous une configuration existante ? » Répondez Non pour une installation neuve (Oui sert à importer une v14, voir plus bas).
3. Hôte et port : l'IP publique ou le domaine que vos clients vont joindre (une adresse IPv6 se met entre crochets, par exemple [2001:db8::1]) et le port UDP, 51820 sauf si vous avez changé le mappage. Les clients reçoivent exactement cette valeur comme Endpoint.

Le DNS, la plage d'adresses des clients et les allowed IPs par défaut se règlent maintenant dans le panneau d'administration, plus dans des variables d'environnement. Pour sauter l'assistant (Ansible, cloud-init), la v15 lit INIT_ENABLED=true avec INIT_USERNAME, INIT_PASSWORD, INIT_HOST et INIT_PORT, au tout premier démarrage seulement ; retirez-les une fois le conteneur lancé pour que le mot de passe ne reste pas dans le fichier. Le générateur peut écrire ces lignes pour vous.

Mot de passe perdu ? Réinitialisez-le depuis le serveur :

cd /etc/docker/containers/wg-easy
sudo docker compose exec -it wg-easy cli db:admin:reset

Si vous venez de la v14

Il n'y a pas de mise à jour sur place. Dans l'ancien panneau, cliquez sur Backup pour télécharger wg0.json et notez vos anciennes variables d'environnement, lancez docker compose down, démarrez le fichier v15 ci-dessus, puis répondez Oui dans l'assistant et envoyez wg0.json : les clés et les clients suivent, pas les anciennes variables, donc redéfinissez DNS et allowed IPs dans le panneau d'administration. Une limite ferme du guide de migration : les hôtes armv6 et armv7 (anciens Raspberry Pi) ne peuvent pas passer en v15 et doivent rester épinglés sur :14.

Vous restez en v14, ou vous quittez le panneau ? Le même fichier de sauvegarde peut être collé dans WireGuard Manager, notre tableau de bord hébergé (gratuit pour 1 serveur et 3 pairs) : comme wg0.json contient la clé privée de chaque client, le .conf et le QR code de chaque appareil sont de nouveau disponibles tout de suite, et il écrit un wg0.conf classique pour wg-quick si vous retirez wg-easy. Rien ne change sur le serveur à l'import.

Ajouter votre premier client

Dans le tableau de bord, cliquez sur New Client, donnez-lui un nom (ex. portable, telephone-pixel), et wg-easy génère la paire de clés et une config prête. Pour un ordinateur, téléchargez le .conf et importez-le dans l'application WireGuard ou les modèles de config ; pour un téléphone, cliquez sur l'icône QR et scannez-le avec l'app mobile WireGuard - aucune saisie, aucun transfert de fichier. L'interrupteur par client désactive un appareil instantanément sans le supprimer, c'est la bonne façon de révoquer un téléphone perdu.

Client importé mais rien ne passe ? Trois causes couvrent presque tous les cas, et chacune a son outil. Le statut reste sans handshake : le port UDP 51820 n'atteint pas le conteneur, lancez le vérificateur de port WireGuard, qui écrit la règle de pare-feu de votre hôte (ufw, firewalld, nftables, iptables) et un test tcpdump qui montre si les paquets arrivent. Handshake correct mais pages qui se figent ou chargent à moitié : un problème de MTU, que le calculateur de MTU dimensionne pour votre lien (reportez la valeur dans la config du client). Vous voulez ne faire passer qu'une partie du trafic, ou garder l'accès à votre réseau local : le calculateur AllowedIPs donne la liste exacte à coller dans les allowed IPs par défaut de wg-easy.

Verrouiller le panneau d'admin - à faire tout de suite, pas plus tard

L'interface web peut créer des clients VPN : un panneau exposé et mal protégé est le vrai danger de wg-easy. Trois couches, par ordre de préférence :

1. Ne publiez jamais 51821 sur Internet. Dans le pare-feu de votre fournisseur VPS, laissez l'UDP 51820 ouvert et gardez le TCP 51821 fermé au monde. N'atteignez le panneau que depuis votre propre IP, ou - le plus propre - connectez-vous d'abord au VPN puis ouvrez le tableau de bord à travers le tunnel, pour que le port d'admin ne soit jamais exposé.

2. Un mot de passe fort, puis la double authentification. La v15 propose une connexion à deux facteurs TOTP : ouvrez le menu en haut à droite, puis Account, activez l'authentification à deux facteurs et scannez le QR code avec votre application d'authentification. Traitez la connexion au panneau comme un mot de passe root.

3. Mettez du TLS devant s'il vous faut l'atteindre à distance : un reverse proxy (Caddy, Traefik, nginx) terminant le HTTPS sur un vrai certificat, idéalement avec une liste d'autorisation. Du HTTP en clair sur un port public est la seule configuration à éviter.

   Depuis la v15.5.0, renseignez aussi TRUSTED_PROXIES avec l'adresse source de votre proxy (pour un conteneur Caddy sur le même réseau Docker, son IP sur ce réseau). wg-easy ne lit alors X-Forwarded-Host et X-Forwarded-For que depuis cette adresse, et les échecs de connexion sont journalisés avec la vraie IP du client : un outil comme CrowdSec bannit l'attaquant et non votre proxy. Une adresse mal écrite empêche le conteneur de démarrer : vérifiez docker compose logs après le changement.

Un VPN auto-hébergé que n'importe quel passant peut s'ajouter est pire que pas de VPN. Le panneau, ce sont les clés du royaume - protégez-le en conséquence.

wg-easy face aux alternatives

• vs PiVPN - PiVPN installe WireGuard directement sur l'hôte et gère les peers au terminal (pivpn add, pivpn -qr). Pas de conteneur, pas d'interface web. Prenez PiVPN pour une machine bare-metal épurée et scriptable ; prenez wg-easy quand vous voulez vraiment un tableau de bord cliquable et des stats en direct.
• vs une config écrite à la main - Éditer wg0.conf soi-même est l'option la plus transparente et la plus légère, idéale pour une machine VPN mono-usage et l'infrastructure-as-code. wg-easy échange un peu de surface supplémentaire (l'app web) contre une gestion des clients rapide et sans CLI.
• vs les autres stacks auto-hébergées - Si vous voulez un mesh (chaque appareil parlant directement aux autres, traversée de NAT gérée pour vous) plutôt qu'un serveur classique en étoile, wg-easy n'est pas la bonne forme ; c'est le terrain de Tailscale/Headscale/NetBird, comparé dans notre guide du meilleur VPN auto-hébergé.

wg-easy tourne aussi très bien aux côtés d'autres conteneurs, d'où son association naturelle avec une installation WireGuard dans Docker plus large.

Quand wg-easy est le bon choix - et quand il ne l'est pas

Utilisez wg-easy quand vous intégrez plusieurs personnes ou appareils, voulez la config par QR code, aimez voir l'état des connexions en direct, ou préférez simplement un panneau à un fichier de config. Il transforme « configurer un client VPN » d'une corvée CLI de cinq minutes en deux clics.

Passez votre chemin quand la machine ne sert qu'un ou deux peers WireGuard (une config à la main est plus simple et a une pièce mobile en moins), quand vous ne pouvez pas garder le port d'admin hors d'Internet en sécurité, ou quand vous voulez en fait un mesh plutôt qu'un serveur. Pour tous les autres, wg-easy est le chemin honnête le plus rapide d'un VPS neuf vers un VPN WireGuard fonctionnel et gérable.

Pour garder l'essentiel sous la main : la WireGuard Cheat Sheet gratuite (PDF de 5 pages en anglais, téléchargement direct, sans inscription) réunit les tables keepalive et MTU, les commandes wg genkey/wg pubkey/wg genpsk et les quatre vérifications serveur en une ligne à lancer d'abord quand un tunnel ne passe aucun trafic. Le WireGuard Self-Hosting Kit payant (9 USD, en anglais) y ajoute une check-list de dépannage de 12 causes et 11 modèles de configuration, dont une pour wg-easy.

Un VPN change votre IP. Il ne change pas votre navigateur.

Un tunnel remplace l'adresse que voit un service. Il ne change rien à ce que votre navigateur annonce de lui-même - polices, écran, fuseau, pile graphique - et cette combinaison suffit souvent à vous reconnaître d'une session à l'autre, tunnel ou pas.

Mesurez votre empreinte de navigateur - mesure passive, aucune question, aucun compte, aucune adresse e-mail.

La limite honnête

wg-easy rend WireGuard plus facile à gérer, pas plus privé ni plus sûr que WireGuard ne l'est déjà. Il partage le noyau de l'hôte, tourne avec NET_ADMIN, et n'est verrouillé qu'autant que l'hôte et le panneau d'admin que vous placez devant. Il n'audite pas vos clients, n'empêche pas seul les fuites DNS (réglez le DNS dans le panneau d'administration et vérifiez), et ne vous protège pas si vous laissez 51821 ouvert. Traitez-le comme une couche de confort par-dessus le vrai WireGuard : déployez-le, durcissez l'hôte et le panneau, gardez le port de données public et le port d'admin privé - et vous avez un VPN auto-hébergé que vous pouvez réellement faire tourner pour tout un foyer sans vivre dans le terminal.