<pclass="section-sub"style="margin-top:1rem">Passez de zéro à un panneau d'administration WireGuard VPN fonctionnel en moins de cinq minutes.</p>
</div>
</section>
<divclass="page-content">
<divclass="container">
<h2id="prérequis">Prérequis</h2>
<ul>
<li>Un serveur Linux accessible depuis l’endroit où vous allez l’administrer</li>
<li><ahref="https://docs.docker.com/engine/install/">Docker</a> et <ahref="https://docs.docker.com/compose/install/">Docker Compose</a> installés</li>
<li>Un nom de domaine pointant vers l’IP de votre serveur</li>
<li>Les ports <strong>80</strong> et <strong>443</strong> ouverts pour Caddy, ainsi que le port UDP de WireGuard ouvert (par défaut <strong>51820</strong>)</li>
</ul>
<divclass="callout">
<p><strong>Caddy nécessite un nom DNS valide</strong>, interne ou public, pointant vers votre serveur afin d'obtenir et de renouveler automatiquement les certificats SSL.</p>
</div>
<hr>
<h2id="déploiement">Déploiement</h2>
<divclass="tab-group">
<divclass="tabs">
<buttonclass="tab-btn active"data-tab="dep-step-1">1. Créer le répertoire</button>
<buttonclass="tab-btn"data-tab="dep-step-2">2. Récupérer le fichier compose</button>
<p>Consultez la <ahref="#env-reference">référence .env</a> ci-dessous pour voir toutes les variables disponibles.</p>
</div>
<divclass="tab-panel"id="dep-step-4">
<pre><code>docker compose up -d</code></pre>
<p>Accédez au panneau via <code>https://vpn.example.com</code>. Caddy obtient et renouvelle automatiquement les certificats SSL.</p>
</div>
</div>
</div>
<hr>
<h2id="env-reference">Référence .env</h2>
<tableclass="env-table">
<thead>
<tr>
<th>Variable</th>
<th>Obligatoire</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>SERVER_ADDRESS</td>
<td>Oui</td>
<td>Nom DNS ou IP de votre serveur. Cela doit correspondre exactement à ce que vous saisissez dans le navigateur, sinon vous aurez des erreurs CSRF.</td>
</tr>
<tr>
<td>DEBUG_MODE</td>
<td>Non</td>
<td>Définissez <code>True</code> pour activer le mode debug de Django. Ne jamais l'utiliser en production. Valeur par défaut : <code>False</code>.</td>
</tr>
<tr>
<td>TIMEZONE</td>
<td>Non</td>
<td>Fuseau horaire de l'application. Utilisez une valeur issue de la <ahref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"target="_blank"rel="noopener">base tz</a>. Valeur par défaut : <code>America/Sao_Paulo</code>.</td>
</tr>
<tr>
<td>EXTRA_ALLOWED_HOSTS</td>
<td>Non</td>
<td>Noms d'hôte supplémentaires que Django doit accepter, séparés par des virgules. <code>SERVER_ADDRESS</code> est toujours inclus. Exemple : <code>app1.example.com,app2.example.com:8443</code>.</td>
</tr>
<tr>
<td>WIREGUARD_STATUS_CACHE_ENABLED</td>
<td>Non</td>
<td>Met en cache l'état de WireGuard afin de réduire les appels à <code>wg</code>. Valeur par défaut : <code>True</code>.</td>
</tr>
<tr>
<td>WIREGUARD_STATUS_CACHE_REFRESH_INTERVAL</td>
<td>Non</td>
<td>Fréquence de rafraîchissement du cache, en secondes. Valeurs autorisées : <code>30</code>, <code>60</code>, <code>150</code>, <code>300</code>. Valeur par défaut : <code>60</code>.</td>
<td>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 : <code>9</code>.</td>
</tr>
<tr>
<td>DISABLE_AUTO_APPLY</td>
<td>Non</td>
<td>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 <code>true</code> pour appliquer les modifications manuellement. Valeur par défaut : <code>false</code>.</td>
</tr>
<tr>
<td>WIREGUARD_MTU</td>
<td>Non</td>
<td>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 <code>1280</code> et <code>9000</code>. 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 : <code>1420</code>.</td>
</tr>
<tr>
<td>VPN_CLIENTS_CAN_ACCESS_DJANGO</td>
<td>Non</td>
<td>Permet aux clients VPN d'accéder directement à l'interface web via l'interface interne à l'adresse <code>http://ip_ou_hostname:8000</code>. Lorsqu'activé, l'adresse interne avec le port <code>:8000</code> doit être ajoutée à <code>EXTRA_ALLOWED_HOSTS</code>, sinon Django bloquera la requête. Valeur par défaut : <code>False</code>.</td>
</tr>
</tbody>
</table>
<hr>
<h2id="mise-à-niveau">Mise à niveau</h2>
<divclass="callout green">
<p><strong>Les données sont conservées dans des volumes Docker.</strong> Une mise à niveau n'affecte ni vos pairs, ni vos règles de pare-feu, ni vos entrées DNS, ni aucune autre configuration.</p>
</div>
<divclass="deploy-steps">
<divclass="deploy-step-card">
<divclass="deploy-step-num">01</div>
<divclass="deploy-step-body">
<divclass="deploy-step-label">Aller dans le répertoire du projet</div>
<pre><code>cd wireguard_webadmin</code></pre>
</div>
</div>
<divclass="deploy-step-card">
<divclass="deploy-step-num">02</div>
<divclass="deploy-step-body">
<divclass="deploy-step-label">Arrêter les services et récupérer les dernières images</div>
<pre><code>docker compose down
docker compose pull</code></pre>
</div>
</div>
<divclass="deploy-step-card">
<divclass="deploy-step-num">03</div>
<divclass="deploy-step-body">
<divclass="deploy-step-label">Sauvegarder vos données</div>
<h3id="caddy-nobtient-pas-de-certificat">Caddy n’obtient pas de certificat</h3>
<ul>
<li>Vérifiez que l’enregistrement A de votre domaine pointe vers l’IP publique du serveur</li>
<li>Vérifiez que les ports 80 et 443 sont ouverts et non bloqués en amont</li>
<li>Consultez les logs de Caddy : <code>docker compose logs caddy</code></li>
</ul>
<h3id="le-panneau-ne-se-charge-pas">Le panneau ne se charge pas</h3>
<ul>
<li>Vérifiez que tous les conteneurs sont en cours d’exécution : <code>docker compose ps</code></li>
<li>Recherchez des erreurs : <code>docker compose logs wireguard_webadmin</code></li>
<li>Vérifiez que <code>SERVER_ADDRESS</code> dans <code>.env</code> correspond exactement à ce que vous saisissez dans le navigateur</li>
</ul>
<h3id="erreurs-csrf-à-la-connexion">Erreurs CSRF à la connexion</h3>
<p><code>SERVER_ADDRESS</code> 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 <code>.env</code> à jour puis redémarrez avec <code>docker compose up -d</code>.</p>
<h3id="les-pairs-wireguard-ne-peuvent-pas-se-connecter">Les pairs WireGuard ne peuvent pas se connecter</h3>
<ul>
<li>Vérifiez que le port UDP de WireGuard est ouvert sur le pare-feu de l’hôte. La valeur par défaut est <strong>51820</strong>, mais si vous exécutez plusieurs instances, chacune doit avoir son propre port.</li>
<li>Assurez-vous que la plage de ports UDP déclarée dans <code>docker-compose.yml</code> 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.</li>
<li>Vérifiez que le transfert IP est activé sur l’hôte : <code>sysctl net.ipv4.ip_forward</code></li>
</ul>
<hr>
<h2id="services-en-cours-dexécution">Services en cours d’exécution</h2>
<tableclass="env-table">
<thead>
<tr><th>Service</th><th>Rôle</th></tr>
</thead>
<tbody>
<tr><td>wireguard-webadmin</td><td>Application Django : interface web et API</td></tr>
<tr><td>caddy</td><td>Proxy inverse et TLS automatique</td></tr>
<tr><td>auth-gateway</td><td>Couche d'autorisation Zero Trust : impose des vérifications d'identité avant de transmettre vers l'upstream</td></tr>
<tr><td>cron</td><td>Tâches planifiées : activation/désactivation des pairs, rafraîchissement du cache</td></tr>
<tr><td>rrdtool</td><td>Historique du trafic : collecte de données RRD et génération de graphiques</td></tr>
<tr><td>dns</td><td>Résolveur basé sur dnsmasq avec prise en charge des listes de blocage par catégories</td></tr>
