---
title: SWAG
description: Configurer SWAG comme reverse proxy avec SSL automatique, exposer vos services en toute sécurité et activer le blocage géographique sur votre homelab.
---


:ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60}

[Swag](https://docs.linuxserver.io/general/swag/) est le noyau de ce homelab. C'est un reverse proxy puissant qui permet d'exposer des services sur internet via des noms de domaine, en se chargeant de l'émission des certificats SSL (pour garder des connexions chiffrées), du routage des requêtes et de la sécurisation des accès (par authentification HTTP ou par SSO comme Authelia ou Authentik). Toute la documentation nécessaire est [disponible ici](https://docs.linuxserver.io/general/swag).

::warning{to="/serveex/core/wireguard"}

SWAG n'a d'utilité que pour exposer vos services sur internet, c'est-à-dire y accéder via une URL publique du type `https://service.mondomaine.fr`. Si vous ne souhaitez pas exposer vos services et préférez systématiquement passer par un VPN pour vous connecter à distance, allez plutôt **par ici**.
::

Ci-dessous, un exemple exposant Dockge. Nous installerons SWAG ainsi que le mod dbip servant à bloquer les connexions selon la géolocalisation, et le mod dashboard qui permet de piloter swag, fail2ban et la géolocalisation.

**Principe d'un reverse proxy et application dans notre cas :**

![Picture](/img/serveex/reverse-proxy.svg)

## Installation

::note

Ce tutoriel part du principe que vous avez un nom de domaine qui pointe vers votre serveur, et que votre box a une règle NAT qui redirige le port `443` vers l'adresse IP et le port `443` de votre serveur. Le nom de domaine d'exemple sera `mondomaine.fr`.
::

::file-tree
---
label: Structure de fichiers à modifier
tree:
  /:
    - srv:
      - docker:
        - swag:
          - config:
            - dns-conf:
              - ovh.ini
            - nginx:
              - dbip.conf
              - nginx.conf
              - proxy-confs:
                - dockge.subdomain.conf
          - compose.yml
          - .env
---
::

::steps{level="3"}
### Déployer la stack

Ouvrez Dockge dans votre navigateur, cliquez sur `compose`, nommez la stack `swag`, et copiez la configuration suivante :

```yaml [compose.yaml]
---
services:
  swag:
    image: lscr.io/linuxserver/swag:latest
    container_name: swag
    cap_add:
      - NET_ADMIN
    env_file:
      - .env
    environment:
      - TZ=Europe/Paris
      - URL=${DOMAIN}
      - EXTRA_DOMAINS=${DOMAINS}
      - SUBDOMAINS=wildcard
      - VALIDATION=dns
      - DNSPLUGIN=${PLUGIN}
      - EMAIL=${EMAIL}
      - DOCKER_MODS=linuxserver/mods:swag-dbip|linuxserver/mods:swag-dashboard|linuxserver/mods:swag-auto-reload
    volumes:
      - /srv/docker/swag/config:/config
    ports:
      - 80:80
      - 443:443
      - 81:81
    restart: unless-stopped
    networks:
      - swag

networks:
  swag:
    name: swag_default
```

::tip{icon=""}
✨ __Astuce :__
ajoutez le label watchtower à chaque conteneur pour activer les mises à jour automatiques

```yaml [compose.yaml]
---
services:
  swag:
    #...
    labels:
      - com.centurylinklabs.watchtower.enable=true
```
::

### Renseigner vos variables d'environnement

Puis dans le fichier `.env` :

```properties [.env]
DOMAIN=
DOMAINS=
EMAIL=
PLUGIN=
```

Remplissez les variables comme suit :

| Propriété               | Valeur                                                                    | Exemples              |
|-------------------------|---------------------------------------------------------------------------|-----------------------|
| `DOMAIN`                | Votre domaine (cela couvre aussi tous les sous-domaines)                  | `mondomaine.fr`       |
| `DOMAINS`               | Vos éventuels autres domaines                                             | `monsecondomaine.fr`  |
| `EMAIL`                 | Votre email, pour générer le certificat                                   | `votre@email.fr`      |
| `PLUGIN`                | Le plugin pour générer le certificat, lié à votre [fournisseur de zone DNS](https://docs.linuxserver.io/general/swag/) | `ovh`<br>`cloudflare` |

### Configurer le plugin DNS OVH

En partant du principe que votre zone DNS est gérée par OVH (sinon, cherchez votre [fournisseur](https://github.com/linuxserver/docker-swag/tree/master/root/defaults/dns-conf)), déployez la stack une première fois. Les logs afficheront un échec de création du certificat SSL faute de configuration `ovh.ini`. Arrêtez la stack.

En ligne de commande, allez dans le dossier dns-conf et modifiez le fichier `ovh.ini` :

::tip{icon="" to="/serveex/files/file-browser-quantum"}
✨ __Astuce pour les allergiques au terminal :__
vous pouvez utiliser **File Browser Quantum** pour naviguer et modifier vos fichiers plutôt que des commandes dans le terminal.
::

```bash [Terminal]
sudo nano /srv/docker/swag/config/dns-conf/ovh.ini
```

Vous devriez voir :

```properties [ovh.ini]
# Instructions: https://github.com/certbot/certbot/blob/master/certbot-dns-ovh/certbot_dns_ovh/__init__.py#L20
# Replace with your values
dns_ovh_endpoint = ovh-eu
dns_ovh_application_key = 
dns_ovh_application_secret = 
dns_ovh_consumer_key = 
```

Authentifiez-vous et créez [votre token ici](https://www.ovh.com/auth/?onsuccess=https%3A%2F%2Fwww.ovh.com%2Fauth%2Fapi%2FcreateToken).

Donnez-lui les permissions suivantes :

* `GET /domain/zone/*`
* `PUT /domain/zone/*`
* `POST /domain/zone/*`
* `DELETE /domain/zone/*`

Notez temporairement les 3 clés et saisissez-les dans `ovh.ini`. (Dans nano, tapez directement, puis :kbd{value="Ctrl+O"}, :kbd{value="Enter"}, :kbd{value="Ctrl+X"} pour enregistrer et quitter)

Enregistrez avec :kbd{value="Ctrl+O"}, puis :kbd{value="Enter"}, et quittez avec :kbd{value="Ctrl+X"}.

### Activer DBIP dans nginx.conf

Configurons maintenant swag pour accéder à DBIP, le module de contrôle d'accès par géolocalisation. Ouvrez le fichier `nginx.conf` :

```bash [Terminal]
sudo nano /srv/docker/swag/config/nginx/nginx.conf
```

Ajoutez la ligne suivante sous la section `http` :

```nginx [nginx.conf]
include /config/nginx/dbip.conf;
```

Redémarrez la stack dans Dockge. Cette fois, le certificat SSL devrait être généré avec succès ! Vérifiez les logs pour confirmer que le serveur est prêt.

### Terminé !
::

## Dashboard
Accédez au tableau de bord en local sur `http://ipdevotreserveur:81`
Sur la gauche, vous verrez la liste des services actuellement « proxifiés » (aucun pour l'instant). Sur la droite, la liste des IP bannies. En dessous, différents indicateurs. Pour plus de détails, [cliquez ici](https://www.linuxserver.io/blog/introducing-swag-dashboard).

![picture](https://www.linuxserver.io/user/pages/03.blog/introducing-swag-dashboard/example.png)

## DBIP
DBIP permet de bloquer les connexions selon les pays. Il s'appuie sur le fichier de configuration nommé `dbip.conf` situé dans `/srv/docker/swag/config/nginx`. [Plus d'infos ici](https://virtualize.link/secure/).

Dans cet exemple, nous le configurerons pour bloquer une liste de pays connus pour être à l'origine de la majorité du trafic malveillant. Nous configurerons aussi une variable pour autoriser le trafic interne au serveur, le réseau local de votre box et un éventuel VPN en 10.x.x.x à accéder à vos services, mais pas l'internet ouvert.

Cette configuration peut être activée ou désactivée service par service (voir l'exemple Dockge plus bas).

::steps{level="3"}
### Ouvrir dbip.conf

```bash [Terminal]
sudo nano /srv/docker/swag/config/nginx/dbip.conf
```

### Faire vos modifications

Reportez-vous à la [documentation](https://github.com/linuxserver/docker-mods/tree/swag-dbip), ou utilisez l'exemple suivant :

```nginx [dbip.conf]
geoip2 /config/geoip2db/dbip-country-lite.mmdb {
    auto_reload 1w;
    $geoip2_data_continent_code   continent code;
    $geoip2_data_country_iso_code country iso_code;
}

# Country Codes: https://en.wikipedia.org/wiki/ISO_3166-2

map $geoip2_data_country_iso_code $geo-whitelist {
    default no;
    FR yes;
}

map $geoip2_data_country_iso_code $geo-blacklist {
    default yes;
    CN no; #Chine
    RU no; #Russie
    HK no; #Hong Kong
    IN no; #Inde
    IR no; #Iran
    VN no; #Vietnam
    TR no; #Turquie
    EG no; #Égypte
    MX no; #Mexique
    JP no; #Japon
    KR no; #Corée du Sud
    KP no; #Corée du Nord
    PE no; #Pérou
    BR no; #Brésil
    UA no; #Ukraine
    ID no; #Indonésie
    TH no; #Thaïlande
}

geo $lan-ip {
    default no;
    10.0.0.0/8 yes;
    172.16.0.0/12 yes;
    192.168.0.0/16 yes;
    127.0.0.1 yes;
}
```

### Enregistrer et redémarrer

Enregistrez et fermez le fichier, puis redémarrez la stack.

### Terminé !
::

Dans les fichiers de configuration de domaine (voir la section suivante), vous pouvez activer ou désactiver la whitelist ou la blacklist ([voir la documentation ici](https://www.forum-nas.fr/threads/tuto-installer-swag-en-docker-reverse-proxy.15057/)). Dans notre cas, la whitelist n'autorise que les requêtes françaises. La blacklist ne bloque que les pays listés. Nous utiliserons la blacklist, comme ceci :

```nginx [some-app.subdomain.conf]{11}
server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name some-app.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    if ($geo-blacklist = no) { return 404; }

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;

        set $upstream_app some-app;
        set $upstream_port 1234;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}
```

## (Facultatif) Exposer Dockge
::note{icon=""}
📋 __Au préalable :__ <br/><br/>
Nous partons du principe que vous avez créé un sous-domaine du type `dockge.mondomaine.fr` dans votre [zone DNS](/general/networking/dns), avec un `CNAME` pointant vers `mondomaine.fr`. À moins d'utiliser [Cloudflare Zero Trust](/serveex/security/cloudflare), nous partons aussi du principe que vous avez redirigé le port `443` de votre box vers le `443` du serveur dans [vos règles NAT](/general/networking/nat).
::

Il est temps d'exposer Dockge sur internet pour accéder à vos conteneurs et les gérer à distance. Nous partons du principe que vous avez configuré le sous-domaine `dockge.mondomaine.fr` avec un `CNAME` pointant vers `mondomaine.fr`.

::warning

Dockge ne gère pas l'authentification multifacteur. L'exposer en ligne pourrait compromettre toutes les machines reliées. Ne le faites que si vous utilisez une solution MFA comme [TinyAuth](/serveex/security/tinyauth) ou [Authentik](/serveex/advanced/authentik/). Sinon, ne l'exposez pas avec SWAG. Utilisez plutôt un VPN comme [Wireguard](/serveex/core/wireguard).
::

::steps{level="3"}
### Créer le fichier subdomain.conf

Ouvrez le fichier `dockge.subdomain.conf` :

```bash [Terminal]
sudo nano /srv/docker/swag/config/nginx/proxy-confs/dockge.subdomain.conf
```

Configurez-le comme ceci :

```nginx [dockge.subdomain.conf]
## Version 2023/12/19

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    
    server_name dockge.*;  # définit le sous-domaine à rediriger

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    #if ($lan-ip = yes) { set $geo-whitelist yes; }
    #if ($geo-whitelist = no) { return 404; }
    if ($geo-blacklist = no) { return 404; } # tous les pays de la blacklist sont interdits

    #include /config/nginx/ldap-server.conf;
    #include /config/nginx/authelia-server.conf;
    #include /config/nginx/authentik-server.conf;

    location / {
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        #include /config/nginx/ldap-location.conf;
        #include /config/nginx/authelia-location.conf;
        #include /config/nginx/authentik-location.conf;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        
        set $upstream_app dockge; # nom du conteneur
        set $upstream_port 5001; # port interne du conteneur (pas le port exposé)
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}
```

Enregistrez et quittez. La configuration se met à jour en quelques secondes.

::note

Par défaut, SWAG ne connaît pas le nom « dockge ». Vous devrez ajouter le réseau de Dockge au `compose.yml` de SWAG.
::

### Ajouter le réseau de Dockge à SWAG

Allez sur la stack SWAG, cliquez sur `edit`, et modifiez le fichier de configuration comme ceci (notez la section `networks`) :

```yaml [compose.yaml]
---
services:
  swag:
    container_name: #...
    # ...
    networks:            # Relie le conteneur au réseau personnalisé

      - dockge           # Nom du réseau tel que défini dans la stack

networks:                # Définit le réseau personnalisé
  # ...
  dockge:                # Nom du réseau tel que défini dans la stack
    name: dockge_default # Vrai nom du réseau externe
    external: true
```

::note

Nous partons du principe que le réseau de Dockge s'appelle `dockge_default`. Vous pouvez vérifier que tout fonctionne en consultant le tableau de bord de SWAG sur `http://ipdevotreserveur:81`.
::

Redéployez la stack SWAG.

### Visiter votre nouveau sous-domaine

Patientez un instant, puis visitez `https://dockge.mondomaine.fr` dans votre navigateur. Vous devriez être redirigé vers Dockge. Vous pouvez aussi vérifier l'état du service depuis le tableau de bord (`http://ipdevotreserveur:81` sur votre réseau local).

### Terminé !
::

## Exposer un autre service avec SWAG
SWAG inclut des modèles pour la plupart des services connus, nommés `nomduservice.subdomain.conf.sample`. Il suffit de créer le sous-domaine dans la zone DNS de votre registrar (comme OVH), de le faire pointer vers votre domaine principal via un CNAME, puis de copier et renommer le fichier d'exemple :

```bash [Terminal]
cd /srv/docker/swag/config/proxy-confs
sudo cp nomduservice.subdomain.conf.sample nomduservice.subdomain.conf
```

::caution

__Si le sous-domaine n'est pas redirigé correctement__
- Ouvrez le fichier et vérifiez le nom du conteneur dans `set $upstream_app nomduconteneur;`{lang=nginx}
- Assurez-vous d'avoir ajouté le réseau du conteneur dans le `compose.yml` de SWAG
::

Vous pouvez aussi personnaliser le sous-domaine en modifiant `server_name votresousdomaine.*;`{lang=nginx} et en renommant le fichier en `votresousdomaine.subdomain.conf`.