2.3 : Publier la forge : reverse proxy et HTTPS

Sommaire

Trois scénarios, un même socle

Votre forge tourne, mais elle n’est joignable que depuis le réseau Docker. Il faut maintenant la publier — et surtout ne pas valider l’assistant d’installation avant d’avoir terminé cette leçon, sous peine de figer une mauvaise URL publique.

Je vous propose trois configurations, de la plus simple à la plus complète :

Scénario Pour qui HTTPS
A — Sans reverse proxy Tester en dix minutes, se faire une idée ❌
B — Derrière Nginx Le cas le plus répandu en entreprise ✅
C — Derrière Traefik Ceux qui viennent de la formation Docker ✅

Ces configurations sont des bases à adapter. Votre reverse proxy a probablement déjà sa propre organisation — fichiers inclus, certificats centralisés, conventions de nommage. Prenez les réglages qui comptent, pas le fichier tel quel.

Et quel que soit le scénario, trois réglages font la différence entre une forge qui marche et une forge qui marche vraiment. Commençons par eux, parce qu’ils expliquent tout le reste.


Les trois réglages qui comptent

1. Forgejo doit connaître son adresse publique

Nous l’avons vu en 2.2 : sans ROOT_URL, Forgejo affiche des URL de clonage fausses et ses redirections d’authentification échouent.

- FORGEJO__server__DOMAIN=forge.nordika.local
- FORGEJO__server__ROOT_URL=https://forge.nordika.local/

La valeur doit correspondre exactement à ce que tape l’utilisateur, protocole compris et barre oblique finale incluse.

Effet de bord utile : lorsque ROOT_URL commence par https, Forgejo bascule automatiquement ses cookies de session en mode sécurisé. Vous n’avez rien de plus à faire.

2. La taille maximale des envois

Voici l’erreur que tout le monde rencontre au premier envoi un peu volumineux :

error: RPC failed; HTTP 413 curl 22 The requested URL returned error: 413

413, c’est le reverse proxy qui refuse la requête, pas Forgejo. Nginx limite par défaut le corps des requêtes à 1 Mo — largement suffisant pour une page web, ridicule pour un dépôt Git.

Vos scripts d’administration ne poseront pas de problème. Mais dès que vous migrerez un dépôt existant avec son historique, ou que vous pousserez une image dans le registre en section 10, vous heurterez cette limite.

3. Les proxys de confiance

Celui-ci est plus subtil, et il n’est documenté nulle part en français.

Par défaut, Forgejo ne fait confiance aux en-têtes X-Forwarded-For que s’ils proviennent de 127.0.0.0/8 ou ::1/128. Or votre reverse proxy est un conteneur, avec une adresse dans un réseau Docker. Ses en-têtes sont donc ignorés.

Conséquence concrète : toutes les connexions apparaissent dans vos journaux avec l’adresse du proxy, jamais celle du poste. Le jour où vous devrez identifier qui a poussé quoi depuis où, vous n’aurez qu’une seule et même IP pour tout le monde. Pour une formation qui vend la traçabilité, ce serait dommage.

- FORGEJO__security__REVERSE_PROXY_TRUSTED_PROXIES=172.16.0.0/12,10.149.8.0/24
- FORGEJO__security__REVERSE_PROXY_LIMIT=1

Indiquez la plage du réseau Docker sur lequel votre proxy joint Forgejo. REVERSE_PROXY_LIMIT=1 signifie « un seul intermédiaire de confiance » — augmentez-le uniquement si vous avez réellement plusieurs proxys en cascade.

Ne mettez pas *. Ça fonctionne, et ça permet à n’importe qui de falsifier son adresse d’origine dans vos journaux.


Scénario A — Sans reverse proxy

Pour tester rapidement, sans certificat ni proxy. C’est une configuration de laboratoire, pas de production.

Décommentez le port dans le compose :

services:
  forge-server:
    ports:
      - "3000:3000"
    environment:
      - FORGEJO__server__DOMAIN=forge.nordika.local
      - FORGEJO__server__ROOT_URL=http://forge.nordika.local:3000/

Puis donnez-lui un nom, au choix :

  • un enregistrement A dans votre DNS interne pointant vers la VM ;
  • ou, pour aller vite, une ligne dans le fichier hosts de votre poste :
192.168.1.50    forge.nordika.local

(sous Windows : C:\Windows\System32\drivers\etc\hosts, à éditer en administrateur)

Redémarrez, puis joignez http://forge.nordika.local:3000.

Pourquoi un nom plutôt que l’IP ? Parce que l’assistant d’installation va figer cette adresse comme URL publique. Utiliser un nom dès maintenant vous permettra de basculer en HTTPS plus tard sans reprendre toutes vos URL de clonage.

Ce que vous acceptez en faisant ce choix

Vos jetons d’accès circulent en clair. Chaque git push transmet votre jeton d’authentification sur le réseau, sans chiffrement. Sur un réseau de laboratoire isolé, le risque est théorique. Sur un réseau d’entreprise, non.

Le registre de conteneurs ne fonctionnera pas simplement. Docker refuse par défaut les registres non chiffrés ; il faudrait le déclarer en registre non sécurisé sur chaque machine cliente. Nous verrons ça en section 10 — mais autant savoir tout de suite que le HTTPS n’est pas seulement une bonne pratique ici, c’est un prérequis fonctionnel.

Considérez donc ce scénario comme temporaire. Si votre forge doit vivre, passez au scénario B ou C avant de créer vos premiers dépôts.


Scénario B — Derrière Nginx

Le cas le plus répandu. Voici un bloc serveur complet et commenté.

# Redirection HTTP vers HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name forge.nordika.local;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name forge.nordika.local;

    # ⚠️ Indispensable : gestion des barres obliques encodées dans les URL
    merge_slashes off;

    # --- Certificat ---
    ssl_certificate     /etc/nginx/certs/forge.nordika.local.crt;
    ssl_certificate_key /etc/nginx/certs/forge.nordika.local.key;
    ssl_protocols       TLSv1.2 TLSv1.3;

    location / {
        # Nom du conteneur sur le réseau Docker partagé
        proxy_pass http://forgejo:3000;

        # En-têtes WebSocket (journaux d'exécution en direct, notifications)
        proxy_set_header Connection         $http_connection;
        proxy_set_header Upgrade            $http_upgrade;

        # Identification de l'appelant
        proxy_set_header Host               $host;
        proxy_set_header X-Real-IP          $remote_addr;
        proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto  $scheme;

        # --- LE réglage à ne pas oublier ---
        client_max_body_size 512M;

        # Ne pas mettre en tampon : Git pousse en flux continu
        proxy_request_buffering off;

        # Les gros envois et les clones volumineux prennent du temps
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

Les points à comprendre

merge_slashes off est le réglage que personne ne devine. Par défaut, Nginx fusionne les barres obliques consécutives dans les URL. Or Git et Forgejo utilisent des barres encodées dans certains chemins — noms de branches contenant un /, références particulières. Sans ce réglage, une partie des opérations échoue de manière déroutante, alors que la navigation courante fonctionne parfaitement. La documentation officielle le marque comme requis.

Connection et Upgrade activent le passage des WebSockets. Sans eux, l’interface fonctionne, mais vous perdez les mises à jour en direct — notamment l’affichage en continu des journaux d’exécution de vos workflows en section 9. C’est typiquement le genre de dysfonctionnement qu’on attribue à tort à l’application.

proxy_pass http://forgejo:3000 utilise le nom du conteneur, pas une IP. Cela suppose que Nginx et Forgejo partagent le réseau nginx-proxy — ce qui est le cas dans notre compose. Si votre Nginx tourne directement sur l’hôte, publiez le port 3000 et pointez sur http://127.0.0.1:3000.

client_max_body_size 512M est la valeur recommandée par la documentation. Certains préfèrent 0 (illimité) ; c’est défendable sur une forge interne, surtout si vous prévoyez de pousser des images volumineuses dans le registre. Ne laissez simplement pas la valeur par défaut.

proxy_request_buffering off évite que Nginx stocke l’intégralité de l’envoi avant de le transmettre. Sur un dépôt volumineux, ça change le comportement côté disque et évite certains délais d’attente.


Scénario C — Derrière Traefik

Si vous venez de la formation Docker, Traefik est déjà en place. Ici, tout se passe par étiquettes dans le compose — aucun fichier de configuration à éditer.

Le nom du réseau partagé : dans nos exemples, il s’appelle nginx-proxy parce que la configuration d’origine tourne derrière Nginx. Ce nom est purement conventionnel — la seule contrainte est que Forgejo et votre reverse proxy soient sur le même réseau Docker. Avec Traefik, on l’appelle plus volontiers traefik, proxy ou web. Adaptez-le partout de façon cohérente : dans la section networks du service, dans la déclaration external: true en bas du fichier, et dans l’étiquette traefik.docker.network.

services:
  forge-server:
    image: codeberg.org/forgejo/forgejo:15
    container_name: forgejo
    networks:
      - forgejo      # réseau privé avec la base
      - traefik      # réseau partagé avec le reverse proxy
    labels:
      - "traefik.enable=true"

      # Routeur
      - "traefik.http.routers.forgejo.rule=Host(`forge.nordika.local`)"
      - "traefik.http.routers.forgejo.entrypoints=websecure"
      - "traefik.http.routers.forgejo.tls=true"
      # Avec un résolveur ACME configuré :
      # - "traefik.http.routers.forgejo.tls.certresolver=monresolver"

      # Service : port interne du conteneur
      - "traefik.http.services.forgejo.loadbalancer.server.port=3000"

      # ⚠️ Indispensable : le conteneur est sur DEUX réseaux
      - "traefik.docker.network=traefik"

networks:
  forgejo:
    driver: bridge
    ipam:
      config:
        - subnet: 10.149.8.0/24
          gateway: 10.149.8.1
  traefik:
    external: true

Le piège des deux réseaux

La dernière étiquette est celle qui fait perdre le plus de temps. Notre conteneur Forgejo est rattaché à deux réseaux : forgejo (privé, avec la base) et celui du reverse proxy.

Sans traefik.docker.network, Traefik choisit une adresse arbitrairement — potentiellement celle du réseau forgejo, qu’il ne peut pas joindre. Résultat : une erreur 502 Bad Gateway parfaitement inexplicable, alors que la configuration semble correcte.

N’oubliez pas non plus que Traefik doit lui-même être rattaché à ce réseau. C’est évident dit comme ça, et c’est pourtant l’autre moitié des 502 inexpliqués.

La taille des envois

Bonne nouvelle : contrairement à Nginx, Traefik n’impose pas de limite de taille de corps de requête par défaut. Vous n’avez rien à faire.

Si vous souhaitez malgré tout en poser une, c’est via un middleware de type buffering — mais attention, activer la mise en tampon des requêtes peut dégrader le comportement sur les gros envois Git. Dans le doute, ne touchez à rien.


Et les autres cas

Apache, HAProxy, Caddy

La documentation officielle fournit des configurations pour chacun. Deux points méritent d’être signalés.

Apache a besoin de l’équivalent du merge_slashes off de Nginx, sous la forme de AllowEncodedSlashes NoDecode et de l’option nocanon sur le ProxyPass. Même cause, même effet.

Caddy est d’une simplicité désarmante, certificat compris :

forge.nordika.local {
  reverse_proxy forgejo:3000
}

Si vous n’avez pas encore de reverse proxy et que vous partez de zéro, c’est une option à considérer sérieusement.

Forgejo peut aussi faire le HTTPS lui-même

Un reverse proxy n’est pas obligatoire. Forgejo sait terminer le TLS directement :

- FORGEJO__server__PROTOCOL=https
- FORGEJO__server__CERT_FILE=/data/certs/forge.crt
- FORGEJO__server__KEY_FILE=/data/certs/forge.key

Il gère même l’obtention automatique de certificats via ACME (ENABLE_ACME=true), avec Let’s Encrypt par défaut ou une autorité ACME interne.

C’est une option viable si la forge est seule sur sa machine. Elle devient moins pertinente dès que d’autres services partagent le même hôte — cas de figure le plus fréquent, et raison pour laquelle nous restons sur un reverse proxy.

Le sous-chemin : à éviter

Il est techniquement possible de publier la forge sur un sous-chemin, du type https://intranet.nordika.fr/forge/. La documentation le documente, et elle l’assortit d’un avertissement de sécurité qu’il faut prendre au sérieux.

Le modèle de sécurité des navigateurs considère comme sûres les interactions au sein d’une même origine. En plaçant la forge sur un sous-chemin d’un domaine qui héberge par ailleurs du contenu saisi par des utilisateurs, cette hypothèse tombe : un contenu malveillant hébergé ailleurs sur la même origine peut monter des attaques contre votre forge. Forgejo n’offre aucune protection contre ce scénario.

Sur un intranet où le même domaine sert un wiki, un portail ou une application métier, le risque est réel. Utilisez un sous-domaine dédié.

Une exception à connaître pour la section 10

Le registre de conteneurs utilise un sous-chemin fixe, /v2, imposé par le client Docker et qu’il est impossible de changer.

Si vous publiez malgré tout Forgejo sur un sous-chemin, il faudra ajouter une route supplémentaire dans votre reverse proxy pour que /v2 soit acheminé correctement. Sur un sous-domaine dédié, la question ne se pose pas — argument supplémentaire en faveur de ce choix.


Le certificat

Trois situations, par ordre de fréquence dans nos environnements.

Une autorité interne (ADCS, PKI maison). C’est le cas le plus courant en entreprise. Émettez un certificat serveur pour le nom de la forge, déposez-le dans votre proxy — et assurez-vous que le certificat de votre autorité est distribué sur les postes, ce qui est probablement déjà fait par GPO.

Rappelez-vous la leçon 1.6 : côté client, si Git refuse la connexion, la bonne réponse est d’installer l’autorité, jamais de désactiver la vérification TLS.

Let’s Encrypt, si votre forge porte un nom public et que vous pouvez satisfaire une validation. Traefik le fait avec un résolveur ACME ; Nginx avec certbot.

Un certificat auto-signé, uniquement pour un laboratoire. Vous devrez l’accepter manuellement dans le navigateur et l’ajouter au magasin de chaque machine cliente. Faisable, mais rapidement pénible dès qu’il y a plus de deux postes.

Le cas de plusieurs noms : si votre forge est joignable à la fois en interne et depuis un réseau distant sous un autre nom, souvenez-vous que ROOT_URL n’accepte qu’une seule valeur. Les URL de clonage afficheront toujours celle-là. Mieux vaut un nom unique, résolu différemment selon l’origine, que deux noms concurrents.


Vérifier que tout est correct

Quatre contrôles, dans cet ordre.

La redirection et le certificat :

curl -I http://forge.nordika.local          # doit renvoyer 301
curl -I https://forge.nordika.local         # doit renvoyer 200

L’adresse d’origine dans les journaux. Le contrôle le plus important, et celui que personne ne fait :

docker compose logs forge-server | tail -20

Vous devez voir l’adresse de votre poste, pas celle du proxy. Si toutes les lignes portent la même IP, revoyez REVERSE_PROXY_TRUSTED_PROXIES.

Les URL de clonage. Une fois l’installation terminée, l’interface doit proposer https://forge.nordika.local/... — jamais localhost ni un port.

Un envoi volumineux. Poussez un dépôt d’une centaine de mégaoctets. Si vous obtenez une erreur 413, c’est la limite du proxy.


Les erreurs classiques

Symptôme Cause probable
502 Bad Gateway Proxy et Forgejo ne partagent pas de réseau, ou mauvais réseau choisi par Traefik
413 Request Entity Too Large client_max_body_size non réglé côté Nginx
Certaines opérations Git échouent, la navigation fonctionne merge_slashes off absent (Nginx) ou AllowEncodedSlashes NoDecode absent (Apache)
Les journaux d’exécution ne défilent pas en direct En-têtes Connection et Upgrade non transmis
URL de clonage en localhost:3000 ROOT_URL absent, ou assistant validé avant la mise en place du proxy
Boucle de redirection infinie X-Forwarded-Proto non transmis : Forgejo croit être en HTTP et redirige indéfiniment
Toutes les connexions ont la même IP REVERSE_PROXY_TRUSTED_PROXIES non adapté au réseau Docker
Déconnexion à chaque page ROOT_URL en https alors que le proxy transmet en http sans l’en-tête de protocole
RPC failed après une longue attente Délais d’attente du proxy trop courts pour un gros dépôt

Ce qu’il faut retenir

  • Publiez avant de valider l’assistant : il fige l’URL publique à partir de l’adresse utilisée.
  • ROOT_URL et DOMAIN doivent refléter exactement l’adresse saisie par l’utilisateur.
  • Nginx limite le corps des requêtes à 1 Mo par défaut : c’est la cause de l’erreur 413.
  • merge_slashes off est requis côté Nginx pour les barres obliques encodées.
  • Les en-têtes Connection et Upgrade conditionnent les mises à jour en direct.
  • Traefik n’impose pas de limite de taille, mais exige traefik.docker.network quand le conteneur est sur plusieurs réseaux.
  • Sans REVERSE_PROXY_TRUSTED_PROXIES adapté, vous perdez l’adresse réelle des utilisateurs dans les journaux.
  • Préférez un sous-domaine dédié à un sous-chemin : Forgejo n’offre aucune protection contre les attaques de même origine.
  • Le registre de conteneurs impose le sous-chemin fixe /v2.
  • Face à un certificat interne : installez l’autorité, ne désactivez jamais la vérification TLS.
  • Sans HTTPS, le registre de conteneurs de la section 10 ne fonctionnera pas simplement.

Dans la leçon suivante

Votre forge est publiée sous son nom définitif, en HTTPS. Il est temps de valider cet assistant d’installation que nous laissons en attente depuis deux leçons.

Nous passerons en revue chacun de ses champs — y compris ceux qu’il vaut mieux ne pas laisser par défaut — puis nous verrons la variante qui évite l’assistant complètement : tout déclarer dans le compose et créer le compte administrateur en ligne de commande. Une forge entièrement décrite par un fichier versionnable, redéployable à l’identique.

C’est aussi le moment où nous désactiverons l’inscription libre, configurerons l’envoi de courriels et poserons les premiers réglages de sécurité.