2.2 : Déployer Forgejo avec Docker Compose

Le fichier, d’abord

Voici le docker-compose.yml que nous allons décortiquer. C’est une configuration réelle, en production — pas un exemple de documentation.

services:
  forge-server:
    image: codeberg.org/forgejo/forgejo:15
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=${DB_PASSWORD}
      - FORGEJO__server__DOMAIN=forge.nordika.local
      - FORGEJO__server__ROOT_URL=https://forge.nordika.local/
      - FORGEJO__server__DISABLE_SSH=true
    restart: always
    networks:
      - forgejo
      - nginx-proxy
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    container_name: forgejo-db
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=forgejo
    networks:
      - forgejo
    volumes:
      - ./postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U forgejo"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  forgejo:
    external: false
    driver: bridge
    enable_ipv6: false
    ipam:
      config:
        - subnet: 10.149.8.0/24
          gateway: 10.149.8.1
  nginx-proxy:
    external: true

Deux services, deux réseaux, une trentaine de lignes. Reprenons chaque bloc.

Le service Forgejo

L’image et son étiquette

image: codeberg.org/forgejo/forgejo:15

Deux choses à noter.

L’image ne vient pas du Docker Hub, mais du registre de Codeberg — l’association qui héberge le projet. C’est le registre officiel de Forgejo.

Derrière un pare-feu d’entreprise ? Si codeberg.org n’est pas joignable depuis votre VM, le projet met à disposition un miroir : remplacez codeberg.org par data.forgejo.org dans le nom de l’image. Et à partir de la section 10, vous pourrez de toute façon recopier cette image dans votre propre registre pour ne plus dépendre d’aucun service externe.

L’étiquette est une version majeure, pas latest. La convention de nommage de Forgejo est précise et vaut la peine d’être connue :

Étiquette Signification
15 La dernière version mineure de la branche 15 (15.0.1, puis 15.0.2…)
15.0 La dernière correction de la 15.0
latest La dernière publiée, majeure comprise

La distinction est capitale, et la documentation officielle est explicite sur ce point : passer d’une majeure à la suivante — de 15 à 16 par exemple — nécessite une opération manuelle et une vérification humaine. En revanche, rester sur l’étiquette 15 vous apporte automatiquement les correctifs mineurs et de sécurité.

Autrement dit : latest sur un service de production, c’est accepter qu’un docker compose pull de routine déclenche une migration majeure non préparée. En épinglant la majeure, la montée de version redevient une décision.

Note de version : cette formation utilise la branche 15. La branche 16 est disponible ; les principes exposés ici restent valables, seule la valeur de l’étiquette change. Vérifiez les notes de version avant de franchir le pas.

Nous reparlerons de cette discipline en section 10, quand vous produirez vos propres images, et en section 14, consacrée à la mise à jour de la forge.

Les identifiants système

- USER_UID=1000
- USER_GID=1000

Le processus dans le conteneur travaillera sous cet identifiant. Le dossier ./forgejo de l’hôte doit lui appartenir, sinon Forgejo ne pourra pas écrire.

C’est la cause numéro un des échecs de premier démarrage. Nous préparerons le terrain correctement plus bas.

Les variables FORGEJO__ : comprendre la convention

C’est le point le plus utile de cette leçon, parce qu’il vous rendra autonome sur toute la configuration à venir.

Forgejo se configure normalement par un fichier app.ini, structuré en sections :

[database]
DB_TYPE = postgres
HOST = db:5432

[server]
DOMAIN = forge.nordika.local

L’image Docker permet de piloter ce fichier par des variables d’environnement, selon une règle simple :

FORGEJO__<section>__<CLE>=<valeur>
        ↑↑        ↑↑
   deux underscores entre chaque partie

Ainsi :

Variable d’environnement Équivalent app.ini
FORGEJO__database__DB_TYPE section [database], clé DB_TYPE
FORGEJO__server__DOMAIN section [server], clé DOMAIN
FORGEJO__service__DISABLE_REGISTRATION section [service], clé DISABLE_REGISTRATION

Le double underscore est le séparateur — un simple underscore fait partie du nom de la clé (DB_TYPE). C’est l’erreur de saisie la plus fréquente.

Cas particulier : les clés qui ne sont dans aucune section — comme APP_NAME — appartiennent à la section DEFAULT, qui s’écrit vide. On obtient donc quatre underscores d’affilée :

- FORGEJO____APP_NAME=Forge Nordika

Au démarrage du conteneur, ces variables sont converties en app.ini. Concrètement, cela signifie que vous pouvez modifier votre configuration en éditant le compose et en redémarrant : c’est reproductible, versionnable, et vous n’avez pas à entrer dans le conteneur pour éditer un fichier.

Une limite à connaître : les variables d’environnement permettent d’ajouter ou de modifier une valeur, jamais d’en supprimer une existante. Pour retirer complètement un paramètre déjà écrit dans app.ini, il faut éditer le fichier directement. Ça peut surprendre le jour où vous retirez une ligne du compose en pensant revenir à l’état antérieur.

La documentation de Forgejo publie un Configuration Cheat Sheet qui recense l’ensemble des sections, des clés et de leurs valeurs par défaut. Une fois la convention comprise, vous savez traduire n’importe quelle ligne de cette page en variable de compose — c’est la compétence qui vous rendra autonome pour toute la suite de la formation.

Les variables serveur : ce qui manquait

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

Ces trois lignes n’étaient pas dans la version initiale, et leur absence provoque le premier bug que rencontrent tous les débutants derrière un reverse proxy.

Sans ROOT_URL, Forgejo ne sait pas sous quelle adresse il est réellement joint. Il voit son propre port interne, pas votre nom public. Résultat : l’interface affiche des URL de clonage du type http://localhost:3000/it/scripts.git, les liens dans les courriels de notification pointent au mauvais endroit, et les redirections d’authentification échouent.

ROOT_URL doit contenir l’adresse complète telle que vos utilisateurs la saisissent, avec le protocole et la barre oblique finale. C’est le nom que vous avez arrêté en leçon 2.1.

DISABLE_SSH=true correspond au choix que nous avons fait : tout se fera en HTTPS avec des jetons d’accès. L’interface cessera alors de proposer des URL de clonage en SSH qui ne fonctionneraient pas.

Si vous souhaitez activer SSH, retirez cette ligne, décommentez le port 222:22 et ajoutez FORGEJO__server__SSH_PORT=222 ainsi que FORGEJO__server__SSH_DOMAIN. Sans ces deux dernières variables, les URL affichées mentionneront le port 22, qui ne répondra pas.

Le redémarrage et les réseaux

restart: always
networks:
  - forgejo
  - nginx-proxy

restart: always relance le conteneur après un redémarrage de l’hôte ou un plantage. Sur un service de production, ce n’est pas optionnel.

Le double rattachement réseau mérite une explication, car c’est un bon exemple de cloisonnement :

  • forgejo est un réseau privé, créé par ce compose, où seuls Forgejo et sa base se parlent.
  • nginx-proxy est un réseau existant, partagé avec le reverse proxy.

Conséquence : la base de données n’est joignable que depuis Forgejo. Elle n’est rattachée qu’au premier réseau. Le reverse proxy, lui, ne voit que Forgejo. C’est exactement le cloisonnement qu’on attend d’un service exposé.

Les volumes

volumes:
  - ./forgejo:/data
  - /etc/localtime:/etc/localtime:ro

Le premier est l’essentiel de ce que vous sauvegarderez : dépôts, configuration, registre, avatars, journaux. Un montage lié, dans un chemin que votre outil de sauvegarde parcourt déjà.

Le second aligne l’horloge du conteneur sur celle de l’hôte, en lecture seule. Cela peut sembler cosmétique — ça ne l’est pas. Vos enregistrements Git sont horodatés, et une forge décalée de deux heures rend les corrélations avec vos journaux d’incident inutilement pénibles.

Les ports : pourquoi il n’y en a pas

Vous remarquerez qu’aucun port n’est publié. Ce n’est pas un oubli.

Forgejo écoute sur le port 3000 à l’intérieur du réseau Docker. Le reverse proxy, présent sur le même réseau nginx-proxy, le joint directement par son nom de conteneur. Aucune raison d’ouvrir un port sur l’hôte.

C’est un bon réflexe de sécurité : ce qui n’est pas publié n’est pas atteignable, même en cas d’erreur de configuration du pare-feu.

Pour un premier test sans reverse proxy, vous pouvez temporairement décommenter - "3000:3000" et joindre http://<ip-de-la-vm>:3000. Pensez à le retirer ensuite.

La dépendance à la base

depends_on:
  db:
    condition: service_healthy

Attention à un malentendu répandu : un depends_on simple garantit seulement l’ordre de démarrage des conteneurs, pas que le service soit prêt. PostgreSQL met quelques secondes à accepter les connexions ; pendant ce temps, Forgejo peut démarrer, échouer, et redémarrer en boucle.

La forme utilisée ici, associée au healthcheck défini sur la base, attend que PostgreSQL réponde réellement. C’est ce qui rend le démarrage fiable après un redémarrage de l’hôte.


Le service PostgreSQL

db:
  image: postgres:16-alpine
  environment:
    - POSTGRES_USER=forgejo
    - POSTGRES_PASSWORD=${DB_PASSWORD}
    - POSTGRES_DB=forgejo
  volumes:
    - ./postgres:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U forgejo"]

Rien d’exotique. La variante alpine réduit l’empreinte de l’image. Les trois variables créent la base et son utilisateur au tout premier démarrage — uniquement au premier : si le dossier de données existe déjà, elles sont ignorées.

C’est important à savoir : changer POSTGRES_PASSWORD dans le compose ne change pas le mot de passe d’une base existante. Vous obtiendriez simplement une erreur d’authentification. La modification se fait dans la base elle-même.

Le healthcheck utilise pg_isready, l’outil standard de PostgreSQL pour tester la disponibilité. C’est lui qui alimente la condition du service précédent.


Les réseaux

networks:
  forgejo:
    driver: bridge
    enable_ipv6: false
    ipam:
      config:
        - subnet: 10.149.8.0/24
          gateway: 10.149.8.1
  nginx-proxy:
    external: true

Le sous-réseau est fixé explicitement, et c’est une pratique que je recommande en entreprise. Par défaut, Docker pioche dans des plages privées qui peuvent entrer en collision avec votre adressage réel — un VPN, un réseau de sites distants, une plage d’imprimantes. En imposant une plage que vous avez choisie et documentée, vous vous épargnez un incident réseau particulièrement pénible à diagnostiquer.

external: true signifie que le réseau nginx-proxy existe déjà et n’est pas géré par ce compose. Il doit avoir été créé au préalable :

docker network create nginx-proxy

Si vous suivez la formation Docker, c’est le réseau sur lequel vit déjà votre reverse proxy.

Ce nom n’a rien d’obligatoire. nginx-proxy reflète simplement le fait que la configuration présentée ici tourne derrière Nginx. La seule contrainte est que Forgejo et votre reverse proxy partagent le même réseau Docker, quel que soit son nom. Avec Traefik, on l’appelle plus souvent traefik, proxy ou web. Si vous le renommez, pensez aux trois endroits concernés : la liste networks du service, la déclaration en bas de fichier, et — pour Traefik — l’étiquette traefik.docker.network que nous verrons en 2.3.


Les secrets : le premier cas d’école

Vous aurez noté que le mot de passe n’est plus écrit en dur, mais référencé :

- POSTGRES_PASSWORD=${DB_PASSWORD}

Docker Compose lit cette valeur dans un fichier .env placé à côté du docker-compose.yml :

# .env
DB_PASSWORD=un_mot_de_passe_long_et_aleatoire

Pourquoi cette séparation ? Parce que ce docker-compose.yml est exactement le genre de fichier que vous allez versionner — c’est le pattern ① de la carte, et nous en ferons un référentiel de stacks en section 5.

Et voilà le piège : si le mot de passe est écrit dans le fichier, il part dans le dépôt. Souvenez-vous de la question du quiz précédent : une fois enregistré, il reste dans l’historique même après suppression.

La bonne pratique se résume en trois points, que nous systématiserons en section 5 :

  1. Le docker-compose.yml est versionné — il décrit l’architecture, il n’a rien de secret.
  2. Le .env n’est jamais versionné — il figure dans le .gitignore.
  3. Un .env.example est versionné, avec les noms de variables et des valeurs factices, pour que vos collègues sachent quoi renseigner.

C’est le premier réflexe de sécurité de cette formation, et il vaut pour toutes les stacks que vous manipulerez ensuite.

Aller plus loin : sortir le secret des variables d’environnement

Un .env correctement exclu du dépôt constitue déjà un niveau acceptable sur une forge interne. Mais la valeur reste visible dans docker inspect et dans l’environnement du processus.

Forgejo propose un mécanisme dédié pour les secrets sensibles : au lieu de la clé habituelle, on utilise une clé suffixée _URI qui pointe vers un fichier. Seul le schéma file: est accepté.

# au lieu de FORGEJO__database__PASSWD
- FORGEJO__database__PASSWD_URI=file:/data/secrets/db_passwd

Le fichier doit évidemment être monté dans le conteneur et lisible par l’utilisateur USER_UID. Le même mécanisme existe pour plusieurs autres secrets, que vous croiserez plus loin dans la formation :

Clé Rôle
[database] PASSWD_URI Mot de passe de la base
[security] SECRET_KEY_URI Clé globale de chiffrement — celle dont la perte rend les secrets 2FA irrécupérables
[security] INTERNAL_TOKEN_URI Jeton de communication interne
[mailer] PASSWD_URI Mot de passe SMTP
[oauth2] JWT_SECRET_URI Signature des jetons OAuth2

Notez au passage SECRET_KEY : Forgejo la génère aléatoirement à l’installation, et elle fait partie intégrante de votre sauvegarde. La perdre revient à perdre l’accès aux données qu’elle protège. Nous y reviendrons en section 14.

Côté PostgreSQL, l’image officielle propose son propre équivalent avec POSTGRES_PASSWORD_FILE.


Préparer l’hôte

Avant le premier lancement :

# Créer l'arborescence
sudo mkdir -p /opt/forgejo
cd /opt/forgejo

# Créer les dossiers de données
mkdir -p forgejo postgres

# Aligner les permissions sur USER_UID / USER_GID
sudo chown -R 1000:1000 forgejo

# Créer le réseau partagé s'il n'existe pas déjà
docker network create nginx-proxy 2>/dev/null || true

Déposez ensuite votre docker-compose.yml et votre .env dans /opt/forgejo, puis protégez ce dernier :

chmod 600 .env

Le premier démarrage

docker compose up -d

Puis, immédiatement :

docker compose logs -f

Ne sautez pas cette étape. Les journaux du premier démarrage vous diront en quelques secondes si la base est jointe, si les permissions sont correctes, et si la configuration a bien été appliquée.

Vérifiez l’état des conteneurs :

docker compose ps

Les deux services doivent être running, et la base marquée healthy.

⚠️ Ne validez pas encore l’assistant

Au premier accès en HTTP, Forgejo n’affiche pas une page de connexion mais un assistant d’installation — une page unique qui reprend la base de données, les chemins, le nom du serveur, l’URL de base, le compte administrateur et quelques options.

Cet assistant écrit /data/gitea/conf/app.ini, et il pré-remplit le champ « Base URL » à partir de l’adresse par laquelle vous l’avez joint.

C’est le piège d’ordonnancement de cette section. Si vous ouvrez http://192.168.1.50:3000 pour valider l’installation, cette adresse se retrouve figée comme URL publique — et toutes les URL de clonage affichées par la suite pointeront vers un port qui ne sera plus exposé.

Montez donc votre reverse proxy avant de valider l’assistant, et accédez-y par son nom définitif. C’est l’objet de la leçon suivante ; nous reviendrons ici ensuite pour terminer l’installation en 2.4.

Vous voulez éviter l’assistant complètement ? C’est possible, et cohérent avec l’esprit de cette formation : en déclarant toute la configuration dans le compose et en ajoutant FORGEJO__security__INSTALL_LOCK=true, la page d’installation devient inaccessible et Forgejo démarre directement. Le compte administrateur se crée alors en ligne de commande. L’avantage est réel — votre forge devient entièrement décrite par un fichier versionnable, reproductible à l’identique. Nous détaillerons cette variante en 2.4, une fois que vous aurez vu ce que l’assistant configure réellement.


Les trois échecs classiques du premier démarrage

Le conteneur redémarre en boucle et les journaux parlent de permissions. Le dossier ./forgejo n’appartient pas à l’UID 1000. Corrigez avec chown -R 1000:1000 forgejo, puis docker compose restart.

Forgejo ne joint pas la base. Vérifiez que FORGEJO__database__HOST correspond bien au nom du service dans le compose (db:5432), et que les deux conteneurs partagent le réseau forgejo. Le nom du service fait office de nom d’hôte à l’intérieur du réseau Docker.

Le réseau nginx-proxy n’existe pas. Compose refuse de démarrer et le signale explicitement. Créez-le avec docker network create nginx-proxy.


Ce qu’il faut retenir

  • Épinglez la version majeure de l’image plutôt que latest : passer d’une majeure à la suivante exige une opération manuelle documentée.
  • Les variables FORGEJO__section__CLE pilotent le fichier app.ini — deux underscores comme séparateur.
  • ROOT_URL et DOMAIN sont indispensables derrière un reverse proxy, faute de quoi les URL affichées seront fausses.
  • Le double réseau isole la base : elle n’est joignable que par Forgejo.
  • Aucun port publié : le reverse proxy joint le conteneur directement par le réseau Docker.
  • depends_on seul ne suffit pas : il faut un healthcheck pour attendre que la base soit réellement prête.
  • Les secrets vont dans un .env non versionné ; le compose, lui, sera versionné.
  • Les permissions du dossier de données doivent correspondre à USER_UID/USER_GID.
  • Les secrets sensibles peuvent être lus depuis un fichier via les clés _URI.
  • Une variable d’environnement ne peut jamais supprimer une valeur existante d’app.ini.
  • Ne validez pas l’assistant d’installation avant d’avoir monté le reverse proxy.

Dans la leçon suivante

Votre forge tourne, mais elle n’est joignable que depuis le réseau Docker — et son assistant d’installation vous attend, qu’il ne faut surtout pas valider tout de suite.

Nous allons la publier proprement : reverse proxy, certificat HTTPS, en-têtes à transmettre, et surtout deux réglages sans lesquels votre forge fonctionnera « presque bien » — la taille maximale des envois, qui fera échouer votre premier push volumineux, et la liste des proxys de confiance, sans laquelle toutes vos connexions apparaîtront dans les journaux avec l’adresse du proxy plutôt que celle du poste.

Ce sera aussi le moment de traiter le cas du certificat émis par votre autorité interne, évoqué en leçon 1.6.

📎 Ressources 2