Installer Forgejo avec Docker et Docker Compose

Forgejo est une forge logicielle libre permettant d’héberger et de gérer des dépôts Git. Il propose les fonctionnalités classiques que l’on attend d’une plateforme de gestion de code source : gestion des dépôts, utilisateurs et organisations, issues, pull requests, gestion des droits, wiki, releases ou encore intégration avec les outils de développement.

Dans ce tutoriel, nous allons voir comment déployer Forgejo à l’aide de Docker et Docker Compose.

L’utilisation de conteneurs permet de disposer d’une installation relativement simple à maintenir et de séparer Forgejo de l’environnement hôte. Les données de l’application seront stockées dans des volumes persistants afin de pouvoir recréer ou mettre à jour le conteneur sans perdre les dépôts et la configuration.

L’objectif de ce tutoriel est donc de partir d’une machine disposant de Docker et de Docker Compose et d’arriver à une instance Forgejo fonctionnelle, accessible depuis un navigateur Web.

Nous verrons notamment :

• la présentation de Forgejo
• la préparation de l’environnement Docker
• la création du fichier compose.yml
• le déploiement du conteneur Forgejo
• la configuration initiale depuis l’interface Web

Présentation de Forgejo

Forgejo est une forge logicielle libre et auto-hébergeable basée sur Git. Le projet fournit une plateforme Web permettant de centraliser le code source et les différents éléments liés au développement d’un projet.

Forgejo fait partie de la famille des solutions dites Git forge, au même titre que GitLab, GitHub ou Gitea. Son objectif est de proposer une plateforme complète pour travailler avec Git, tout en permettant à l’organisation de conserver la maîtrise de son infrastructure et de ses données.

Forgejo et Git

Il est important de distinguer Git de Forgejo.

Git est le système de gestion de versions distribué qui permet notamment de suivre les modifications apportées aux fichiers d’un projet.

Forgejo vient se placer au-dessus de Git en fournissant une interface Web et différents services permettant de travailler avec des dépôts Git. Il permet par exemple de créer un dépôt, gérer les utilisateurs et leurs permissions, consulter l’historique des modifications ou encore effectuer des pull requests.

On peut donc résumer simplement :

• Git : gestionnaire de versions ;
• Forgejo : plateforme permettant d’héberger et de gérer des dépôts Git.

Forgejo n’est donc pas un remplacement de Git, mais une solution permettant de construire sa propre forge Git.

Les principales fonctionnalités de Forgejo

Forgejo propose un ensemble de fonctionnalités permettant de couvrir la majorité des besoins d’une forge Git.

On retrouve notamment :

• Dépôts Git : création et hébergement de dépôts Git ;
• Utilisateurs : gestion des comptes et des droits ;
• Organisations : regroupement de dépôts et gestion des membres ;
• Issues : suivi des tâches, bugs et demandes d’évolution ;
• Pull Requests : revue et intégration des modifications ;
• Wiki : documentation associée aux projets ;
• Releases : publication de versions des logiciels ;
• Tags et branches : gestion des différentes versions du code ;
• Webhooks : déclenchement d’actions lors d’événements sur les dépôts ;
• Clés SSH : authentification des utilisateurs Git ;
• Tokens d’accès : authentification pour les outils et scripts ;
• Actions : automatisation de tâches et de workflows ;
• API : intégration avec d’autres applications et outils.

L’interface Web permet également de consulter directement les fichiers, l’historique Git, les branches, les commits et les différences entre les versions.

Forgejo, Gitea, GitLab et GitHub

Forgejo peut être comparé à plusieurs solutions connues dans l’écosystème Git.

GitHub est une plateforme SaaS très largement utilisée. Elle permet de bénéficier d’une infrastructure hébergée, mais les données et la plateforme sont opérées par GitHub.

GitLab propose une plateforme beaucoup plus large, avec notamment des fonctionnalités importantes autour du CI/CD, de la gestion de projets et de la sécurité. Il peut cependant être plus conséquent à déployer et à administrer.

Gitea est une autre forge Git légère et auto-hébergeable. Forgejo est issu d’un fork de Gitea et conserve une philosophie similaire autour d’une solution relativement légère et simple à administrer.

Forgejo est donc particulièrement intéressant lorsque l’on recherche une forge Git libre, légère et auto-hébergeable, sans forcément avoir besoin de l’ensemble des fonctionnalités proposées par une plateforme comme GitLab.

Pourquoi utiliser Forgejo ?

L’un des principaux intérêts de Forgejo est de pouvoir héberger soi-même sa forge Git.

Dans un environnement professionnel ou personnel, cela permet notamment de conserver les dépôts et les données associées sur sa propre infrastructure.

Forgejo peut ainsi être utilisé pour :

• héberger les dépôts Git d’une entreprise ;
• centraliser les scripts d’administration système ;
• gérer le code source d’applications internes ;
• héberger des projets personnels ;
• mettre en place une forge Git pour une équipe ;
• remplacer une forge Git SaaS pour certains usages ;
• intégrer Git dans une infrastructure existante.

Son fonctionnement relativement léger permet également de l’installer sur une infrastructure disposant de ressources limitées.

Pourquoi déployer Forgejo avec Docker ?

Dans ce tutoriel, Forgejo sera déployé avec Docker Compose.

Cette approche permet de décrire l’installation dans un fichier compose.yml et de gérer facilement le conteneur ainsi que les volumes nécessaires à la persistance des données.

L’utilisation de Docker présente plusieurs avantages :

• installation reproductible ;
• déploiement rapide ;
• isolation de l’application ;
• gestion simple des versions de Forgejo ;
• séparation entre l’application et le système hôte ;
• sauvegarde facilitée des données persistantes ;
• possibilité d’intégrer facilement Forgejo derrière un reverse proxy.

Le principe sera donc de faire fonctionner Forgejo dans un conteneur Docker et de conserver les données de l’application dans des volumes persistants.

Une fois le conteneur déployé, Forgejo pourra ensuite être placé derrière un reverse proxy comme Nginx , Traefik ou Caddy, notamment pour utiliser un nom DNS et activer HTTPS.

Dans la suite du tutoriel, nous allons maintenant préparer l’environnement puis procéder au déploiement de Forgejo avec Docker Compose.

Déployer Forgejo

Une fois n’est pas coutume, si vous avez l’habitude de suivre mes tutoriels dans lesquels nous déployons des applications avec Docker et Docker Compose, j’ai déjà préparé le fichier compose.yml nécessaire au déploiement de Forgejo.

Le fichier est disponible sur mon dépôt GitHub : Docker Compose — Forgejo

Vous pouvez donc directement récupérer le fichier et l’adapter à votre environnement si nécessaire.

Dans la suite du tutoriel, je vais tout de même détailler les différents éléments du fichier Compose afin de comprendre ce qui est déployé et comment les données de Forgejo sont persistées.

1. Commencer par créer un dossier sur votre serveur Linux pour stocker les fichiers (compose.yml et .env) ainsi que les données persistante.

mkdir -p /opt/forgejo
cd /opt/forgejo

2. Récupérer les fichiers sur le dépôt :

bash <(wget -qO- https://forge.rdr-it.com/romain/Docker-Compose/raw/branch/main/get.sh) Forgejo

3. Configurer le fichier .env qui va nous permettre de configurer Forgejo :

cp .env.example .env
nano .env

Les variables a éditer :

• FORGE_SERVER_DOMAIN : Domain de publication forge.domain.tld
• FORGE_SERVER_ROOT_URL : URL de base http(s)://forge.domain.tld/
• POSTGRES_PASSWORD : mot de passe pour la base de données Postgres

4. Démarrer le conteneur et vérifier les logs :

docker compose up -d
docker compose logs -f

Si vous souhaitez passer par un reverse proxy, il est impératif de le configurer maintenant, car l’assistant d’installation va detecter l’URL.

Configurer un reverse proxy pour Forgejo

Dans ce tutoriel, je vais vous expliquer comment configurer Traefik et Nginx comment reverse pour publier votre Forge.

Doc officielle :forgejo.org/docs/latest/admin/setup/reverse-proxy

Traefik

Dans ce tutoriel, j’ai fais le choix d’utiliser Traefik pour publier Forgejo, afin de ne pas modifier le fichier compose.yml, nous allons utiliser la fonctionnalité override qui va nous permettre de déclarer le complément de configuration nécessaire pour Fogejo.

1. Créer un fichier compose.override.yml et mettre le contenu ci-dessous qui doit être adapter à votre environnement.

nano compose.override.yml

services:
  forge-server:
    networks:
      - proxy
    environment:
      FORGEJO__openid__ENABLE_OPENID_SIGNIN: false
      # Enable registration
      FORGEJO__service__DISABLE_REGISTRATION: false
      # Landing page
      FORGEJO__server__LANDING_PAGE: explore
      # Footer
      FORGEJO__other__SHOW_FOOTER_VERSION: false
      FORGEJO__other__SHOW_FOOTER_TEMPLATE_LOAD_TIME: false
      FORGEJO__other__SHOW_FOOTER_POWERED_BY: false
    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"
      # Service : port interne du conteneur
      - "traefik.http.services.forgejo.loadbalancer.server.port=3000"
      # Indispensable : le conteneur est sur DEUX reseaux
      - "traefik.docker.network=proxy"

networks:
  proxy:
    external: true

2. Redémarrer le conteneur :

docker compose up -d --force-recreate

3. Vérifier dans le Tableau de bord de Traefik la détection des labels.

Nginx

Voici un exemple de configuration de virtualhost pour Nginx :

# 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;
    }
}

Accéder à l’assistant de configuration de Forgejo

Maintenant que tout est prêt, on va pouvoir accéder à l’assistant de configuration de Forgejo depuis un navigateur en entrant l’URL de la forge.

L’assistant se présente sous un grand formulaire avec plusieurs sections de configuration, vérifier la configuration de la base de données, le domaine et l’URL dans un premier temps.

Ici, ce qui nous intéresse particulière, c’est la création d’un compte administrateur, qui se trouve en bas du formulaire (assistant), entrer un nom d’utilisateur (pas admin), une adresse e-mail et le mot de passe et cliquer sur le bouton Installer Forgejo.

Patienter pendant l’initialisation de Forgejo …

Vous avez maintenant votre propre Forge Git.

Pourquoi j’ai choisi Forgejo à la place de GitLab

Si vous êtes un lecteur régulier de RDR-IT, vous avez certainement remarqué que j’ai progressivement délaissé GitLab au profit de Forgejo. Je vais vous expliquer ici pourquoi j’ai fait ce choix.

Pendant plusieurs années, j’ai utilisé GitLab comme forge personnelle, mais également dans différents environnements professionnels. Même si GitLab est une excellente solution et propose énormément de fonctionnalités, j’ai commencé à chercher une alternative pour plusieurs raisons.

La première concerne les ressources nécessaires. Forgejo est particulièrement léger et peut fonctionner avec seulement quelques centaines de mégaoctets de RAM, là où GitLab demande rapidement plusieurs gigaoctets de mémoire. Pour une forge qui héberge principalement des dépôts Git, cette différence peut être assez importante, notamment sur des infrastructures où les ressources sont limitées.

Le deuxième point concerne les mises à jour de GitLab. Elles sont relativement fréquentes et certaines évolutions ou changements de comportement m’ont régulièrement obligé à adapter mes scripts et mes playbooks. À l’inverse, je trouve les mises à jour de Forgejo beaucoup plus simples à gérer dans mon environnement.

Forgejo est également beaucoup plus simple à mettre en œuvre et à administrer. Là où GitLab embarque énormément de composants et de fonctionnalités, Forgejo reste concentré sur son rôle de forge Git. Cela permet d’avoir une solution plus légère, plus simple à maintenir et qui correspond mieux à mes besoins.

Enfin, un dernier point a fini de me convaincre : Forgejo propose un fonctionnement proche de celui que l’on retrouve sur GitHub, notamment avec les Actions et les workflows. Pour quelqu’un qui travaille déjà avec Git et les workflows GitHub, la transition est donc relativement naturelle.

Ce changement ne signifie pas que GitLab est une mauvaise solution. Au contraire, GitLab reste extrêmement complet et sera probablement plus adapté à certains besoins, notamment lorsque l’on souhaite disposer d’une plateforme DevOps complète avec un ensemble très riche de fonctionnalités.

Dans mon cas, pour une forge Git personnelle et pour mes besoins quotidiens, Forgejo répond simplement mieux à mes besoins, tout en étant beaucoup plus léger et plus simple à maintenir.

Conclusion

Dans ce tutoriel, nous avons vu comment déployer Forgejo avec Docker et Docker Compose afin de disposer d’une forge Git fonctionnelle et facilement maintenable.

L’installation reste relativement simple et permet de disposer rapidement d’une instance Forgejo, tout en conservant les données de l’application dans des volumes persistants.

Ce tutoriel constitue cependant uniquement la première étape. Dans les prochains tutoriels, nous irons plus loin dans la configuration de Forgejo et son intégration dans une infrastructure existante.

Nous verrons notamment comment :

• intégrer Forgejo avec Authentik en OpenID Connect afin de centraliser l’authentification ;
• mettre en place un Runner Forgejo pour exécuter les workflows et automatiser certaines tâches ;
• configurer les workflows et les Actions ;
• et probablement revenir sur certains aspects de l’administration et de la sécurisation de Forgejo.

L’objectif sera ainsi de construire progressivement une forge Git complète, intégrée à l’infrastructure et capable d’aller au-delà du simple hébergement de dépôts.

FAQ