Offre Durée limitée : -10% sur tout le site* avec le code ELYPSEWELCOME10

Installer Forgejo sur un VPS Linux avec Docker : votre serveur Git auto-hébergé

Mis à jour le 22 novembre 2026 10 min de lecture 11 sections

Si vous cherchiez un serveur Git léger et que Soft Serve ne vous convient plus, la réponse qui revient dans les discussions d'auto-hébergeurs est Forgejo. Un fil de r/selfhosted pose justement la question, avec Forgejo en tête des recommandations. Je n'ai pas pu en relire le contenu pour ce guide : tout ce qui suit s'appuie sur la documentation officielle de Forgejo.

Forgejo est une forge logicielle libre : dépôts Git, interface web, tickets, pull requests, registre de paquets et CI intégrée (Forgejo Actions). Ce guide l'installe avec PostgreSQL via Docker Compose sur un VPS Linux, puis configure le SSH Git, le HTTPS, l'inscription fermée, un runner, les sauvegardes et les mises à jour.

Forgejo, Soft Serve, Gitea, GitLab : lequel choisir ?

Soft Serve est un serveur Git minimaliste, piloté par SSH. Forgejo et Gitea sont des forges complètes, légères, écrites en Go. Forgejo est un fork de Gitea. GitLab est une plateforme DevOps beaucoup plus large, donc plus gourmande.

CritèreSoft ServeForgejoGiteaGitLab
Interface web, tickets, pull requestsNon, orienté terminalOuiOuiOui
CI intégréeNonForgejo ActionsActionsGitLab CI/CD
Base de donnéesFichiersSQLite, MySQL, PostgreSQLSQLite, MySQL, PostgreSQLPostgreSQL intégré
Ressources sur un petit VPSTrès faiblesFaibles (application Go)Faibles (application Go)8 Go de mémoire au minimum selon la documentation

Sur les ressources, le seul chiffre officiel que je peux citer est celui de GitLab : sa documentation d'exigences recommande 8 vCPU et 16 Go de RAM, et indique qu'il peut fonctionner avec 8 Go minimum dans un environnement contraint. La documentation Docker de Gitea ne publie pas d'exigence matérielle, ni celle de Forgejo. Je ne donne donc pas de chiffre pour ces deux forges : mesurez avec docker stats après quelques jours d'usage réel. Pour un petit VPS avec une poignée d'utilisateurs, Forgejo ou Gitea tiennent largement là où GitLab sature.

Gitea a connu des failles exploitées récemment, que nous avons détaillées dans cette actualité. Quelle que soit la forge, la règle est la même : accès restreint et mises à jour régulières. Pour une comparaison générale, voyez aussi notre guide Forgejo et Gitea sur un VPS.

Prérequis

Installer Forgejo et PostgreSQL avec Docker Compose

La documentation Forgejo propose l'image rootless. Elle écoute en SSH sur le port 2222 du conteneur et stocke ses données dans /var/lib/gitea. Le tag 17-rootless suit la branche 17.

mkdir -p ~/forgejo/data ~/forgejo/postgres
cd ~/forgejo
sudo chown -R 1000:1000 data
openssl rand -base64 24   # à utiliser comme mot de passe PostgreSQL

Créez ensuite compose.yaml. Remplacez le mot de passe de démonstration par celui généré, et le domaine par le vôtre :

services:
  server:
    image: codeberg.org/forgejo/forgejo:17-rootless
    container_name: forgejo
    user: 1000:1000
    restart: always
    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=CHANGEZ_MOI
      - FORGEJO__server__DOMAIN=git.exemple.fr
      - FORGEJO__server__ROOT_URL=https://git.exemple.fr/
      - FORGEJO__server__SSH_DOMAIN=git.exemple.fr
      - FORGEJO__server__SSH_PORT=2222
      - FORGEJO__service__DISABLE_REGISTRATION=true
    volumes:
      - ./data:/var/lib/gitea
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"
      - "2222:2222"
    depends_on:
      - db

  db:
    image: postgres:17
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=CHANGEZ_MOI
      - POSTGRES_DB=forgejo
    volumes:
      - ./postgres:/var/lib/postgresql/data

Points d'attention :

  • L'exemple officiel utilise postgres:14. Choisissez plutôt une version majeure encore maintenue : PostgreSQL 14 arrive en fin de vie, voir notre actualité sur le sujet. Pour durcir l'accès à la base, lisez Installer PostgreSQL sur un VPS Linux. Ici, la base n'a aucun port publié : seul le conteneur Forgejo la joint.
  • Le port web est publié sur 127.0.0.1 uniquement : le reverse proxy sera la seule porte d'entrée.
  • Les variables FORGEJO__section__CLE écrasent les valeurs de app.ini. DISABLE_REGISTRATION et REQUIRE_SIGNIN_VIEW appartiennent à la section [service], DOMAIN, ROOT_URL, SSH_DOMAIN et SSH_PORT à [server].
docker compose up -d
docker compose logs -f server

Créer l'administrateur et fermer l'inscription

Avec DISABLE_REGISTRATION=true, personne ne peut s'inscrire depuis l'interface : seul un administrateur crée les comptes. Créez le premier compte en ligne de commande :

docker exec forgejo forgejo admin user create \
  --admin --username admin --email admin@exemple.fr \
  --random-password

La commande affiche le mot de passe généré. Les options --random-password et --must-change-password sont documentées dans la référence de la ligne de commande. Si vous voulez aussi cacher vos dépôts publics aux visiteurs anonymes, ajoutez FORGEJO__service__REQUIRE_SIGNIN_VIEW=true.

Le HTTPS derrière un reverse proxy

Forgejo écoute en HTTP sur le port 3000. Placez devant lui un reverse proxy qui gère le certificat. Avec Caddy, le certificat Let's Encrypt est obtenu et renouvelé tout seul. Le guide Caddy en reverse proxy Docker détaille l'installation. Si vous préférez Nginx, voyez Nginx en reverse proxy. Le Caddyfile minimal :

git.exemple.fr {
    reverse_proxy 127.0.0.1:3000
}

Ouvrez les ports 80 et 443 dans votre pare-feu, ainsi que le port SSH Git choisi (voir Ouvrir des ports avec UFW). Vérifiez que ROOT_URL correspond bien à l'adresse HTTPS : sinon les liens de clonage et les redirections seront faux. La page reverse proxy de la documentation couvre les autres cas.

Le SSH Git : port 2222 ou port 22

Les clones par SSH (git clone ssh://git@git.exemple.fr:2222/utilisateur/depot.git) passent par le serveur SSH intégré à l'image rootless.

Option 1 : le port 2222, la plus simple

C'est la configuration du compose ci-dessus : le port 2222 de l'hôte est publié vers le 2222 du conteneur, et SSH_PORT=2222 fait afficher le bon port dans les URL de clone. Ajoutez votre clé publique dans les paramètres de votre compte Forgejo, puis testez :

ssh -F /dev/null -p 2222 git@git.exemple.fr

La documentation officielle utilise le même test avec le port 222 de l'hôte. Le choix du port hôte est libre, tant que SSH_PORT y correspond.

Option 2 : des URL de clone sans port, sur le 22

Pour obtenir git@git.exemple.fr:utilisateur/depot.git, le port 22 de l'hôte doit mener à Forgejo. Deux approches :

  • Déplacer le sshd de l'hôte (par exemple sur le port 2200), publier "22:2222" dans le compose et mettre SSH_PORT=22. Gardez une session ouverte pendant le changement et testez la nouvelle connexion avant de la fermer, voir Configurer une clé SSH sans perdre l'accès.
  • Un passthrough : l'utilisateur git de l'hôte transmet les connexions au conteneur. Cela garde le sshd de l'hôte sur le 22, mais demande un montage supplémentaire. Je ne le détaille pas ici, car je n'ai pas vérifié la procédure dans la documentation actuelle de Forgejo.

Dans tous les cas, protégez le port SSH exposé contre les tentatives répétées avec Fail2ban.

Mettre en place un runner Forgejo Actions

Forgejo Actions est la CI intégrée, proche de GitHub Actions. Elle est activée par défaut. Les jobs sont exécutés par un runner, un programme séparé du serveur. La documentation insiste : le runner exécute du code distant, lisez la page sécurité des Actions avant de l'ouvrir à d'autres personnes.

Déployer le runner avec Docker

La documentation du runner Docker utilise un conteneur docker-in-docker privilégié et l'image data.forgejo.org/forgejo/runner. Au moment de l'écriture, l'exemple officiel est en tag 13. Vérifiez le tag actuel dans la documentation avant de copier.

mkdir -p ~/forgejo-runner/data/.cache
cd ~/forgejo-runner
sudo chown -R 1001:1001 data
chmod 775 data/.cache && chmod g+s data/.cache
docker run --rm data.forgejo.org/forgejo/runner:13 \
  forgejo-runner generate-config > data/runner-config.yml
services:
  docker-in-docker:
    image: docker:dind
    container_name: docker_dind
    privileged: true
    command: ['dockerd', '-H', 'tcp://0.0.0.0:2375', '--tls=false']
    restart: unless-stopped

  runner:
    image: data.forgejo.org/forgejo/runner:13
    container_name: runner
    depends_on:
      docker-in-docker:
        condition: service_started
    environment:
      DOCKER_HOST: tcp://docker-in-docker:2375
    user: 1001:1001
    volumes:
      - ./data:/data
    restart: unless-stopped
    command: 'forgejo-runner daemon --config runner-config.yml'

Enregistrer le runner

  1. Dans Forgejo, ouvrez /admin/actions/runners (instance entière) ou la page runners d'un dépôt, d'un utilisateur ou d'une organisation, puis cliquez sur Create new runner.
  2. Forgejo affiche un UUID et un jeton. Copiez-les dans la section server de data/runner-config.yml :
server:
  connections:
    forgejo:
      url: https://git.exemple.fr/
      uuid: <UUID>
      token: <JETON>

Définissez aussi les labels du runner dans le même fichier : ils indiquent quels jobs il accepte et dans quelle image. La page de configuration du runner explique leur choix. Puis lancez docker compose up -d. La commande forgejo-runner register est dépréciée dans la documentation actuelle : préférez cette méthode.

Un premier workflow

Dans un dépôt, créez .forgejo/workflows/ci.yml. Le champ runs-on doit correspondre à un label de votre runner (ici docker) :

on: [push]
jobs:
  test:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - run: echo "La CI tourne sur mon VPS"

Si les builds d'images Docker échouent, consultez la page accès à Docker des Actions. Pour un usage ouvert à des tiers, séparez le runner du serveur qui détient vos dépôts : un runner compromis ne doit pas atteindre vos données.

Les sauvegardes avec forgejo dump

La commande forgejo dump crée une archive de l'instance. Options documentées : --file (nom du fichier, - pour la sortie standard), --type (zip par défaut, mais aussi tar.gz, tar.zst, etc.) et --tempdir.

docker exec forgejo forgejo dump --type tar.gz --file /tmp/forgejo-dump.tar.gz --tempdir /tmp
docker cp forgejo:/tmp/forgejo-dump.tar.gz ./sauvegardes/
docker exec forgejo rm /tmp/forgejo-dump.tar.gz

Si la commande ne trouve pas la configuration, passez-lui le chemin de app.ini avec l'option de configuration. Quelques règles issues de la documentation de sauvegarde :

  • Elle recommande vivement d'arrêter Forgejo pendant une sauvegarde, pour obtenir un état cohérent.
  • Sauvegardez app.ini, en particulier SECRET_KEY et JWT_SECRET, ainsi que les clés d'hôte SSH. Sans elles, une restauration pose problème.
  • Avec PostgreSQL, vous pouvez aussi sauvegarder la base avec pg_dump.
  • À la restauration, remettez base, dépôts et configuration, démarrez Forgejo, puis relancez depuis /admin/monitor/cron la régénération des fichiers SSH si nécessaire.

Une archive qui reste sur le VPS n'est pas une sauvegarde. Copiez-la ailleurs avec rsync vers un serveur distant et chiffrez-la : Chiffrer ses sauvegardes hors site. Planifiez le tout avec un timer systemd ou cron. Chez ElypseCloud, les sauvegardes de serveur sont une option : renseignez-vous sur la page des VPS Linux. Testez de toute façon une restauration sur une machine vierge.

Les mises à jour

Le tag 17 suit les versions mineures de la branche 17, le tag 17.0 le dernier correctif. Le passage de la version X à X+1 est une opération manuelle : lisez le guide de mise à jour avant de changer de tag. Procédure habituelle pour une mise à jour mineure :

  1. Faites un dump et une copie de app.ini.
  2. docker compose pull
  3. docker compose up -d
  4. Vérifiez les journaux avec docker compose logs server et la version affichée dans le pied de page de l'interface.

Les ancien tags s'accumulent : nettoyez-les avec Docker prune. Mettez à jour sans traîner : une forge exposée sur Internet est une cible, comme l'a montré la faille GitLab CI/CD.

Checklist avant mise en production

  • Inscription fermée (DISABLE_REGISTRATION=true) et compte admin avec mot de passe fort, idéalement double authentification.
  • PostgreSQL sans port publié, mot de passe généré.
  • HTTPS actif, ROOT_URL correct, port 3000 limité à 127.0.0.1.
  • Pare-feu : 80, 443 et le port SSH Git seulement.
  • Runner isolé si des tiers peuvent lancer des jobs.
  • Dump testé et copié hors du VPS.
  • Surveillance de l'espace disque : Surveiller l'espace disque.

En résumé

Forgejo avec PostgreSQL et Docker Compose donne un serveur Git complet qui tient sur un petit VPS, là où GitLab demande au moins 8 Go de mémoire selon sa documentation. Fermez l'inscription, mettez-le derrière un reverse proxy HTTPS, isolez le runner, sauvegardez hors site et mettez à jour régulièrement. Pour héberger Forgejo avec un accès root complet, partez d'un VPS Linux.

FAQ

Forgejo est-il un bon remplaçant de Soft Serve ?

Les deux ne jouent pas dans la même catégorie. Soft Serve est un serveur Git minimaliste en ligne de commande, Forgejo ajoute une interface web, les tickets, les pull requests et la CI. Si vous cherchez simplement à héberger des dépôts, Forgejo fait le travail et reste raisonnable en ressources avec PostgreSQL.

Quel port SSH choisir pour les clones Git ?

Le plus simple est de publier le SSH du conteneur sur le port 2222 de l'hôte et de l'indiquer dans SSH_PORT. Pour des URL de clone sans port, déplacez le sshd de l'hôte sur un autre port et publiez le 22 vers le conteneur, en gardant l'administration du VPS accessible.

Comment empêcher n'importe qui de créer un compte ?

Définissez DISABLE_REGISTRATION à true dans la section service de la configuration. Seul un administrateur peut alors créer des comptes. Vous pouvez ajouter REQUIRE_SIGNIN_VIEW pour exiger une connexion même pour lire les dépôts.

Faut-il mettre le runner Forgejo Actions sur le même VPS que Forgejo ?

Pour un usage personnel, c'est possible, mais le runner exécute du code distant et le conteneur docker-in-docker est privilégié. Dès que des tiers peuvent déclencher des jobs, placez le runner sur une machine séparée de celle qui détient vos dépôts.

forgejo dump suffit-il comme sauvegarde ?

C'est un bon point de départ : l'archive regroupe base, dépôts et données. Conservez-la hors du VPS, testez la restauration et sauvegardez aussi app.ini et vos secrets. La documentation recommande d'arrêter Forgejo pour une sauvegarde cohérente. Les sauvegardes sont en option chez ElypseCloud.

Comment mettre Forgejo à jour sans perdre mes dépôts ?

Faites un dump, puis docker compose pull et docker compose up -d. Le tag majeur suit les versions mineures. Le passage d'une version majeure à la suivante demande de lire le guide de mise à jour officiel avant de changer de tag.

Forgejo consomme-t-il moins de ressources que GitLab ?

Oui, de façon nette. GitLab documente 8 Go de mémoire au minimum et recommande 8 vCPU et 16 Go. Forgejo et Gitea sont des applications Go bien plus légères. Mesurez avec docker stats sur votre propre VPS, car la charge dépend de vos dépôts et de votre CI.