Interface web pour administrer un serveur WireGuard sans manipuler directement les fichiers de configuration.

• Gestion des pairs (création, édition, révocation).
• Génération de configuration client.
• Export via QR code et fichier.
• Authentification administrateur.
• Healthcheck API intégré (/api/health).
• Déploiement simple avec Docker / Docker Compose.
• Envoie de mail pour l'enrollement

docker run -d \
  --name wireguard-ui \
  --cap-add NET_ADMIN \
  --sysctl net.ipv4.ip_forward=1 \
  --sysctl net.ipv4.conf.all.src_valid_mark=1 \
  -p 8000:8000 \
  -p 51820:51820/udp \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=yourpassword \
  -e SECRET_KEY=your-secret-key \
  -v wg_config:/etc/wireguard \
  -v wireguard-ui_data:/var/lib/wireguard-ui \
  cyrius44/wireguard-ui:latest

Open http://localhost:8000 and log in with your admin credentials.

services:
  wireguard-ui:
    image: cyrius44/wireguard-ui:latest
    container_name: wireguard-ui
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
    ports:
      - "8000:8000"
      - "51820:51820/udp"
    environment:
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=changeme
      - SECRET_KEY=your-secret-key
    volumes:
      - wg_config:/etc/wireguard
      - wireguard-ui_data:/var/lib/wireguard-ui

volumes:
  wg_config:
  wireguard-ui_data:

docker compose up -d --build

• 8000 — Wireguard UI + API
• 51820 — Wireguard port for clients

GET /api/health returns a JSON status payload.

• SECRET_KEY must be set to a non-default value or the app will refuse to start.
• Always change ADMIN_PASSWORD on first launch.
• If you expose the UI publicly, enable HTTPS at the reverse proxy level.

• ADMIN_USERNAME : identifiant admin initial.
• ADMIN_PASSWORD : mot de passe admin initial.
• ADMIN_EMAIL : email admin initial.
• SECRET_KEY : clé de signature JWT (obligatoire en production).
• ACCESS_TOKEN_EXPIRE_MINUTES : durée de vie des tokens.
• BCRYPT_ROUNDS : coût de hash des mots de passe.

• LOG_LEVEL : niveau de logs (INFO, DEBUG, etc.).
• APP_VERSION : version exposée par l’application.

• DB_PATH : URL de connexion SQLAlchemy.
  • Par défaut : sqlite+aiosqlite:////var/lib/wireguard-ui/wireguard_ui.db

• WIREGUARD_AUTOSTART : active le démarrage automatique WireGuard au lancement.

• MAIL_FROM : adresse expéditrice.
• MAIL_NAME : nom expéditeur.

• net.ipv4.ip_forward=1 : nécessaire pour forwwarder les appels vers la carte principale
• net.ipv4.conf.all.src_valid_mark=1 : nécessaire pour l'identification des sources

D’autres réglages SMTP sont configurables depuis l’interface d’administration.

Deux volumes sont nécessaires :

• Remplacer SECRET_KEY par une valeur longue et aléatoire.
• Changer immédiatement les identifiants admin par défaut.
• Utiliser un reverse proxy TLS (Traefik, Nginx, Caddy).
• Sauvegarder régulièrement les volumes /etc/wireguard et /var/lib/wireguard-ui.

git clone https://github.com/cyr-ius/wireguard-ui.git
cd wireguard-ui

Le docker-compose.yaml fournit déjà des valeurs par défaut, mais il est recommandé de les surcharger en production :

ADMIN_USERNAME=admin
ADMIN_PASSWORD=change-me-now
SECRET_KEY=replace-with-a-long-random-secret
LOG_LEVEL=INFO

Le projet est découpé en deux applications :

• backend/ (API FastAPI)
• frontend/ (Angular)

• Python 3.14+
• uv (gestion des dépendances Python)
• Node.js 22+ et npm

Depuis la racine du dépôt :

cd backend
uv sync --extra dev

uv run uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Dans un autre terminal :

cd frontend
npm ci

npm start

Par défaut, le frontend est accessible sur http://localhost:4200.

Les contributions sont bienvenues : bugfix, amélioration UX, sécurité, documentation.

1. Forker le dépôt et créer une branche :

   git checkout -b feat/ma-feature

2. Développer avec des commits atomiques et des messages explicites.

3. Vérifier localement avant PR :

   # Backend
   cd backend
   uv run ruff check src
   uv run mypy src
   
   # Frontend
   cd ../frontend
   npm run build

4. Ouvrir une Pull Request avec :

   • le contexte / problème,
   • la solution proposée,
   • les tests effectués,
   • les éventuels impacts (migration, compatibilité, sécurité).

• Éviter les changements hors-sujet dans une même PR.
• Préférer les PR petites et faciles à relire.
• Mettre à jour la documentation si comportement fonctionnel modifié.

Un fichier AGENTS.md est fourni à la racine pour aider les agents (Codex, assistants IA, etc.) à installer les dépendances et lancer les vérifications nécessaires à l’analyse du projet.

MIT — voir LICENSE.