DEV Community

Cover image for 🚀 SWAG : Le Reverse Proxy Docker qui va révolutionner votre homelab !
Onepoint profile image yohann streibel
yohann streibel for Onepoint

Posted on

🚀 SWAG : Le Reverse Proxy Docker qui va révolutionner votre homelab !

#adventoftech2025 #docker #homelab #cloud

Salut les dev ! 👋

Aujourd'hui, je vais vous parler d'un outil qui a littéralement transformé ma façon de gérer mes services web : SWAG (Secure Web Application Gateway). Si vous êtes dans le monde du homelab ou si vous déployez plusieurs services web, cet article va vous intéresser !

Table des matières

  1. Mais qu'est-ce que SWAG exactement ?
  2. Pourquoi SWAG plutôt qu'autre chose ?
  3. Notre architecture cible
  4. Configuration réseau et DNS (étape cruciale !)
  5. Installation avec Docker Compose
  6. Configuration étape par étape
  7. Ajouter nos premiers services
  8. Troubleshooting réseau
  9. Tips et bonnes pratiques
  10. Sécurisation avec Authelia (bonus)
  11. Résultat final
  12. Debugging courant
  13. Conclusion
  14. Pour aller plus loin

🤔 Mais qu'est-ce que SWAG exactement ?

SWAG, c'est un reverse proxy tout-en-un basé sur nginx qui gère automatiquement vos certificats SSL Let's Encrypt. En gros, c'est votre portier numérique qui :

  • 🔒 Sécurise automatiquement vos services avec des certificats SSL
  • 🌐 Expose vos services Docker sur des sous-domaines propres
  • 🛡️ Protège vos applications avec une authentification centralisée
  • 📋 Gère tout ça avec de la configuration simple

💭 Pourquoi SWAG plutôt qu'autre chose ?

Avant SWAG, j'utilisais nginx classique avec certbot... Quelle galère ! 😅 Entre les renouvellements de certificats qui plantent, les configs nginx à maintenir manuellement, et la gestion des domaines, c'était un vrai casse-tête.

SWAG résout tout ça d'un coup :

  • Certificats wildcard automatiques
  • Configs pré-faites pour les services populaires
  • Intégration native avec Docker
  • Support de l'authentification (Authelia, OAuth, etc.)

🏗️ Notre architecture cible

Imaginons qu'on veuille exposer plusieurs services :

  • Un Home Assistant sur homeassistant.mondomaine.fr
  • Un serveur de fichiers sur files.mondomaine.fr
  • Une interface d'administration sur admin.mondomaine.fr

Avec SWAG, tout passe par un seul point d'entrée sécurisé !

🌐 Configuration réseau et DNS (étape cruciale !)

Avant de plonger dans Docker, il faut préparer le terrain côté réseau. C'est souvent l'étape que les débutants oublient ! 😅

1. Configuration chez votre provider (exemple Free)

Chez Free, il faut :

  1. Se connecter à l'interface Freebox : http://mafreebox.freebox.fr
  2. Aller dans "Paramètres de la Freebox" > "Gestion des ports"

  3. Créer une redirection de port :

    • Port externe : 443 (HTTPS)
    • Port interne : 443
    • IP destination : IP locale de votre serveur (ex: 192.168.1.100)
    • Protocole : TCP

  4. Optionnel : Port 80 pour les redirections HTTP vers HTTPS :

    • Port externe : 80
    • Port interne : 80
    • IP destination : 192.168.1.100

💡 Tip sécurité : Au lieu d'exposer directement les ports 80/443, vous pouvez utiliser des ports custom (ex: 8443) et faire la redirection. Plus sécurisé !

2. Configuration DuckDNS

DuckDNS, c'est le DNS dynamique gratuit parfait pour les homelabs !

  1. Inscription sur duckdns.org
  2. Créer votre domaine : monhomelab.duckdns.org
  3. Noter votre token (on en aura besoin dans Docker)

💡 Alternative DNS providers : DuckDNS n'est pas obligatoire ! SWAG supporte plein d'autres providers :

Gratuits :

  • DuckDNS (duckdns) - Le plus simple pour débuter
  • FreeDNS (freedns) - Autre alternative gratuite
  • No-IP (noip) - Service populaire avec version gratuite

Payants (mais plus pro) :

  • Cloudflare (cloudflare) - Excellent, rapide et pas cher
  • OVH (ovh) - Provider français
  • Gandi (gandi) - Interface simple
  • Route53 (route53) - AWS, très fiable
  • DigitalOcean (digitalocean) - Simple à utiliser
  • Namecheap (namecheap) - Bon rapport qualité/prix

Configuration type pour Cloudflare :

environment:
  - URL=mondomaine.com
  - VALIDATION=dns
  - DNSPLUGIN=cloudflare
  - EMAIL=votre-email@example.com
  - CLOUDFLARETOKEN=votre-api-token-cloudflare

La liste complète est dispo dans la doc SWAG ! 📚

3. Vérification IP publique

Votre DuckDNS doit pointer vers votre IP publique :

# Vérifier votre IP publique
curl ifconfig.me

# Vérifier que DuckDNS pointe bien dessus
nslookup monhomelab.duckdns.org
Enter fullscreen mode Exit fullscreen mode

Si les IPs correspondent, c'est bon ! 🎯

4. Test de connectivité

Avant même de démarrer SWAG, testez que le port forwarding fonctionne :

# Sur votre serveur local, démarrez un serveur web simple
python3 -m http.server 8080

# Depuis l'extérieur, testez avec votre domaine
curl http://monhomelab.duckdns.org:8080
Enter fullscreen mode Exit fullscreen mode

Si ça marche, vous êtes prêts pour SWAG !

📦 Installation avec Docker Compose

Première étape : créer notre docker-compose.yml pour SWAG.

version: "3.8"

networks:
  web-proxy:
    external: false

services:
  swag:
    image: lscr.io/linuxserver/swag:latest
    container_name: swag
    cap_add:
      - NET_ADMIN
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Paris
      - URL=monhomelab.duckdns.org  # Votre domaine DuckDNS
      - VALIDATION=duckdns          # Validation via DuckDNS
      - DUCKDNSTOKEN=12345678-1234-1234-1234-123456789012  # Votre token DuckDNS
      - SUBDOMAINS=wildcard         # Permet *.monhomelab.duckdns.org
      - EMAIL=votre-email@example.com
      - ONLY_SUBDOMAINS=false       # Important pour que le domaine principal marche
    volumes:
      - ./swag/data:/config
    ports:
      - "80:80"     # HTTP (redirections vers HTTPS)
      - "443:443"   # HTTPS (vos services sécurisés)
    networks:
      - web-proxy
    restart: unless-stopped
Enter fullscreen mode Exit fullscreen mode

🔧 Configuration étape par étape

1. Préparation des variables d'environnement

Les variables importantes à comprendre :

  • URL : Votre domaine complet (DuckDNS, Cloudflare, ou autre provider)
  • VALIDATION=duckdns : Type de validation selon votre provider (voir liste ci-dessus)
  • SUBDOMAINS=wildcard : Génère un certificat pour tous vos sous-domaines
  • DUCKDNSTOKEN : Token/API key de votre provider DNS
  • ONLY_SUBDOMAINS=false : Permet d'utiliser le domaine principal aussi

💭 Pourquoi DuckDNS dans cet exemple ? C'est gratuit et ultra simple pour débuter ! Mais si vous avez déjà un domaine chez Cloudflare/OVH/Gandi, utilisez-le directement.

2. Configuration DuckDNS automatique

SWAG va automatiquement :

  1. Mettre à jour votre IP sur DuckDNS
  2. Valider votre domaine via l'API DuckDNS
  3. Générer le certificat wildcard
  4. Renouveler automatiquement tout ça !

C'est la magie de cette combo SWAG + DuckDNS ! ✨

3. Premiers pas après démarrage 

# Démarrer SWAG
docker-compose up -d swag

# Vérifier les logs
docker logs swag

# Vous devriez voir quelque chose comme :
# "Server ready"
# "Certificate renewal successful"
Enter fullscreen mode Exit fullscreen mode

4. Structure des dossiers créés

Après le premier démarrage, SWAG crée cette structure :

swag/data/
├── nginx/
│   ├── nginx.conf
│   ├── site-confs/
│   └── proxy-confs/     # ← Les configs de nos services !
├── keys/
│   └── letsencrypt/     # ← Nos certificats SSL
└── log/
Enter fullscreen mode Exit fullscreen mode

🎯 Ajouter nos premiers services

Service 1 : Home Assistant

Créons notre service Home Assistant dans le même réseau :

# Ajout dans docker-compose.yml
  homeassistant:
    image: homeassistant/home-assistant:stable
    container_name: homeassistant
    environment:
      - TZ=Europe/Paris
    volumes:
      - ./homeassistant/data:/config
    networks:
      - web-proxy
    ports:
      - "8123:8123"  # Optionnel, pour accès direct local
    restart: unless-stopped
Enter fullscreen mode Exit fullscreen mode

Configuration du proxy dans SWAG

Créer le fichier : swag/data/nginx/proxy-confs/homeassistant.subdomain.conf

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name homeassistant.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app homeassistant;
        set $upstream_port 8123;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }

    # Support des WebSockets (important pour Home Assistant !)
    location /api/websocket {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app homeassistant;
        set $upstream_port 8123;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
Enter fullscreen mode Exit fullscreen mode

Test de votre configuration

Une fois tout configuré, testez vos URLs :

  • ✅ https://monhomelab.duckdns.org → Page par défaut SWAG
  • ✅ https://homeassistant.monhomelab.duckdns.org → Votre Home Assistant
  • ✅ Certificat SSL valide et wildcard !

🔧 Troubleshooting réseau

Problème : "Site inaccessible depuis l'extérieur"

  1. Vérifiez votre IP publique : 
# Sur votre serveur
curl ifconfig.me

# Doit correspondre à :
nslookup monhomelab.duckdns.org
Enter fullscreen mode Exit fullscreen mode
  1. Testez le port forwarding : 
# Depuis l'extérieur (4G par exemple)
telnet monhomelab.duckdns.org 443
Enter fullscreen mode Exit fullscreen mode
  1. Vérifiez les logs SWAG : 
docker logs swag | grep -i "certificate\|error\|duckdns"
Enter fullscreen mode Exit fullscreen mode

Problème : "DuckDNS validation failed"

Vérifiez votre token DuckDNS :

# Test manuel de l'API DuckDNS
curl "https://www.duckdns.org/update?domains=monhomelab&token=VOTRE_TOKEN&ip="
Enter fullscreen mode Exit fullscreen mode

Doit retourner "OK" si le token est bon.

Problème : "Certificat non généré"

Souvent c'est un souci de timing. DuckDNS peut mettre quelques minutes à propager :

# Redémarrez SWAG après quelques minutes
docker restart swag

# Surveillez les logs
docker logs -f swag
Enter fullscreen mode Exit fullscreen mode

🔥 Tips et bonnes pratiques

1. Réseau Docker dédié

Créez toujours un réseau dédié pour vos services web :

# Créer le réseau manuellement
docker network create web-proxy

# Ou le définir comme external dans docker-compose
networks:
  web-proxy:
    external: true
Enter fullscreen mode Exit fullscreen mode

2. Gestion des logs

Surveillez les logs pour déboguer :

# Logs SWAG en temps réel
docker logs -f swag

# Logs nginx spécifiques
docker exec swag tail -f /config/log/nginx/error.log
Enter fullscreen mode Exit fullscreen mode

3. Test de configuration

Avant de redémarrer, testez toujours :

# Test de la config nginx
docker exec swag nginx -t

# Rechargement à chaud (si test OK)
docker exec swag nginx -s reload
Enter fullscreen mode Exit fullscreen mode

4. Wildcard certificates

Avec les certificats wildcard, vous pouvez ajouter autant de sous-domaines que vous voulez sans renouveler le certificat !

🛡️ Sécurisation avec Authelia (bonus)

Pour aller plus loin, on peut ajouter une authentification centralisée :

# Service Authelia
  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    volumes:
      - ./authelia/data:/config
    networks:
      - web-proxy
    environment:
      - TZ=Europe/Paris
    restart: unless-stopped
Enter fullscreen mode Exit fullscreen mode

Et dans notre config nginx, on ajoute :

# En haut du fichier de config de service
include /config/nginx/authelia-server.conf;

# Dans la location /
include /config/nginx/authelia-location.conf;
Enter fullscreen mode Exit fullscreen mode

🎯 Résultat final

Une fois tout configuré, vous avez :

✅ https://homeassistant.monhomelab.duckdns.org - Sécurisé avec SSL

✅ https://files.monhomelab.duckdns.org - Protégé par authentification

✅ https://admin.monhomelab.duckdns.org - Accessible uniquement pour les admins

Le tout avec un seul certificat wildcard qui se renouvelle automatiquement !

🐛 Debugging courant

Problème : "502 Bad Gateway" 

# Vérifier que le service target existe
docker ps | grep nom-du-service

# Vérifier la résolution DNS interne
docker exec swag nslookup nom-du-service
Enter fullscreen mode Exit fullscreen mode

Problème : Certificat non généré 

# Vérifier les logs de génération
docker logs swag | grep -i "certificate\|error\|duckdns"

# Tester manuellement DuckDNS
curl "https://www.duckdns.org/update?domains=VOTRE_DOMAINE&token=VOTRE_TOKEN&ip="
Enter fullscreen mode Exit fullscreen mode

Problème : WebSockets qui ne passent pas

Ajoutez toujours ces headers dans vos configs :

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_cache_bypass $http_upgrade;
Enter fullscreen mode Exit fullscreen mode

🎉 Conclusion

SWAG a vraiment simplifié ma vie de homelabber ! En quelques fichiers de config, j'ai :

  • Des certificats SSL automatiques
  • Des sous-domaines propres pour tous mes services
  • Une authentification centralisée
  • Une maintenance quasi nulle

Si vous hésitez encore à passer le cap, foncez ! C'est un investissement en temps qui se rentabilise très vite.

🔗 Pour aller plus loin

Et vous, vous utilisez quoi comme reverse proxy ? Dites-moi en commentaire ! 💬

docker #nginx #ssl #homelab #reverseproxy #swag #letsencrypt #devops

Top comments (1)

Collapse
 
nicolas_albert_2dc941b15a profile image
Nicolas Albert •

Traefik fait déjà tout ça, avec un simple label sur les services docker compose pour les exposer sous leur propre sous-domaine et un autre label pour activer l'authentification Authelia.
Mais cool d'avoir d'autres alternatives.