Héberger Gitea vous-même pour votre propre serveur Git

Vous voulez vos dépôts sur une machine que vous contrôlez : du code privé qui ne quitte jamais votre infrastructure, pas de prix par utilisateur, et une interface web que votre équipe sait déjà utiliser. Gitea offre tout ça dans un seul conteneur : navigation dans les dépôts, demandes de fusion, tickets, registre de paquets et Git par HTTPS et par SSH. Ce guide vous mène d’un serveur vide à Gitea sur votre propre domaine, avec le HTTPS via Caddy, les envois SSH sur leur propre port et une sauvegarde que vous avez restaurée au moins une fois. La dernière partie montre la version en un clic sur Railyard.

Ce guide utilise Gitea 28.2.0, la version actuelle, depuis le registre de Gitea à docker.gitea.com. Gitea est passé des numéros 1.x à 28.0.0 en septembre 2026, donc une étiquette « 28 » est bien la version la plus récente, pas une coquille.

Ce qu’il vous faut

• Un serveur. Gitea est léger. Un Hetzner CX23 (2 vCPU, 4 Go de RAM, 40 Go NVMe) coûte 5,99 €/mois hors TVA et suffit largement pour une petite équipe. Les dépôts grossissent, alors surveillez le disque.
• Un domaine ou un sous-domaine que vous pouvez pointer vers le serveur. Ce guide utilise git.example.com.
• Un accès SSH en root ou avec un utilisateur qui a sudo.
• Un port libre sur l’hôte pour Git par SSH. Le SSH du serveur reste sur le port 22, donc le serveur SSH de Gitea prend le port 222, la correspondance utilisée dans la documentation de Gitea.

Étape 1 : Pointer le DNS vers le serveur et le mettre à jour

Créez le serveur et ajoutez un enregistrement A pour git.example.com vers son adresse IPv4 publique. Faites-le en premier : Caddy ne peut obtenir un certificat qu’une fois que le nom pointe vers votre serveur.

ssh root@203.0.113.20
apt update && apt upgrade -y

Depuis votre poste, vérifiez l’enregistrement :

dig +short git.example.com

Vous devriez voir l’adresse IP de votre serveur. Sinon, continuez et revérifiez avant l’étape 5.

Étape 2 : Installer Docker

Gitea et Caddy tournent dans des conteneurs, donc Docker Engine avec le plugiciel Compose suffit :

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
docker compose version

Vous devriez voir une ligne Docker Compose version.

Étape 3 : Écrire le fichier Compose

Gitea utilise SQLite tant que vous ne le dirigez pas vers une autre base de données. SQLite garde tout dans un seul volume et convient très bien à une petite équipe, donc ce guide l’utilise (la FAQ parle de Postgres). Créez le dossier :

mkdir -p /opt/gitea/backups
cd /opt/gitea

Enregistrez ceci dans /opt/gitea/compose.yaml, avec votre propre domaine :

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    depends_on:
      - gitea

  gitea:
    image: docker.gitea.com/gitea:28.2.0
    restart: unless-stopped
    environment:
      USER_UID: "1000"
      USER_GID: "1000"
      GITEA__server__DOMAIN: git.example.com
      GITEA__server__ROOT_URL: https://git.example.com/
      GITEA__server__SSH_DOMAIN: git.example.com
      GITEA__server__SSH_PORT: "222"
    volumes:
      - gitea-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "222:22"

volumes:
  gitea-data:
  caddy-data:
  caddy-config:

Ce qu’il fait :

• L’image, USER_UID/USER_GID, les montages du fuseau horaire et la correspondance 222:22 viennent directement de la documentation Docker de Gitea. Dans le conteneur, un serveur SSH écoute sur le port 22 pour Git; l’hôte l’expose sur le 222.
• Les variables GITEA__section__CLÉ définissent des valeurs dans le app.ini de Gitea. ROOT_URL fait générer des liens HTTPS, et SSH_PORT fait afficher 222 dans les adresses de clonage. Elles préremplissent aussi l’assistant d’installation.
• Le port web de Gitea, 3000, n’est pas publié. Caddy le joint par le réseau Compose, donc la seule entrée web passe par le HTTPS.
• Tout ce que Gitea stocke (dépôts, base SQLite, fichiers téléversés et app.ini) vit dans le volume gitea-data. Un volume nommé règle aussi les droits sur les fichiers pour vous.

Étape 4 : Écrire le Caddyfile

Enregistrez ceci dans /opt/gitea/Caddyfile :

git.example.com {
	encode zstd gzip
	reverse_proxy gitea:3000
}

Caddy obtient un certificat Let’s Encrypt pour le domaine, redirige le HTTP vers le HTTPS et relaie l’interface web et Git par HTTPS vers Gitea. Git par SSH ne passe pas par Caddy : il va directement au port 222. Vérifiez les deux fichiers :

docker compose config --quiet && echo "compose ok"
docker compose run --rm --no-deps caddy caddy validate --config /etc/caddy/Caddyfile

Vous devriez voir compose ok, puis Valid configuration.

Étape 5 : Ouvrir les ports et démarrer

Autorisez les ports 80, 443 et 222 dans le pare-feu de votre fournisseur infonuagique. Démarrez ensuite la pile :

docker compose up -d
docker compose ps
docker compose logs -f caddy

Vous devriez voir caddy et gitea à l’état Up, et Caddy indiquer qu’il a obtenu un certificat pour git.example.com. Faites Ctrl+C et ouvrez https://git.example.com. Vous devriez voir la page d’installation de Gitea.

Étape 6 : Terminer l’assistant d’installation

Gitea n’a pas de compte par défaut : la première visite ouvre une page d’installation unique. Vérifiez les valeurs, que les variables d’environnement ont pour la plupart déjà remplies :

• Database Type : SQLite3, avec le chemin /data/gitea/gitea.db.
• SSH Server Port 222 et Gitea Website URL https://git.example.com/. L’encadré Environment Configuration en bas liste les variables GITEA__ qui seront écrites dans /data/gitea/conf/app.ini.
• Only administrators can create user accounts (no self-registration) : cochez-la si seule votre équipe doit avoir des comptes.
• Administrator Account Settings, sous Optional Settings : choisissez un nom d’utilisateur, un courriel et un mot de passe. La page le dit clairement : si vous sautez cette partie, le premier utilisateur qui s’inscrit devient administrateur.

Cliquez sur Install Gitea. Vous devriez arriver sur votre tableau de bord, connecté comme administrateur.

Testez maintenant les deux façons d’envoyer du code. Ajoutez votre clé publique sous Settings → SSH / GPG Keys, créez un dépôt nommé test-repo, puis depuis votre poste :

git clone ssh://git@git.example.com:222/youradmin/test-repo.git
git clone https://git.example.com/youradmin/test-repo.git test-repo-https

Les deux clonages devraient réussir. Utilisez la forme ssh:// avec le port : la forme courte git@hôte:propriétaire/dépôt utilise toujours le port 22.

Étape 7 : Sauvegarder Gitea

gitea dump écrit les dépôts, la base de données, app.ini et les fichiers téléversés dans une seule archive. Il doit tourner avec l’utilisateur git, parce que Gitea refuse de tourner en root. Enregistrez ceci dans /opt/gitea/backup.sh :

#!/usr/bin/env bash
set -euo pipefail
cd /opt/gitea
docker compose exec -T -u git -w /tmp gitea gitea dump -c /data/gitea/conf/app.ini --file - > "backups/gitea-$(date +%F).zip"
find backups -name 'gitea-*.zip' -mtime +14 -delete

--file - envoie l’archive sur la sortie standard, donc elle arrive directement sur l’hôte. Rendez le script exécutable, lancez-le et planifiez-le à 3 h avec crontab -e :

chmod +x /opt/gitea/backup.sh
/opt/gitea/backup.sh
unzip -l /opt/gitea/backups/gitea-$(date +%F).zip | tail -3

0 3 * * * /opt/gitea/backup.sh

Vous devriez voir une liste de fichiers qui se termine par un total. Copiez aussi les archives hors du serveur, par exemple avec rsync vers une autre machine.

Pour restaurer dans une installation neuve, démarrez Gitea sur un volume vide, copiez l’archive dedans et remettez chaque partie à sa place :

docker compose up -d gitea
docker compose cp backups/gitea-2026-05-25.zip gitea:/tmp/restore.zip
docker compose exec gitea sh -c 'mkdir -p /tmp/r && cd /tmp/r && unzip -q /tmp/restore.zip && mkdir -p /data/gitea/conf /data/git/repositories && cp app.ini /data/gitea/conf/app.ini && cp -a data/. /data/gitea/ && cp -a repos/. /data/git/repositories/ && chown -R git:git /data/gitea /data/git'
docker compose restart gitea
docker compose exec -u git gitea gitea -c /data/gitea/conf/app.ini admin regenerate hooks

Ces commandes suivent les étapes de restauration de la documentation de sauvegarde de Gitea pour Docker. Vous devriez retrouver vos dépôts et votre compte administrateur, sans page d’installation.

Étape 8 : Mettre à jour

Gitea applique ses migrations de base de données au démarrage. Lisez les notes de version, faites une sauvegarde, changez l’étiquette de l’image dans compose.yaml, puis :

/opt/gitea/backup.sh
docker compose pull gitea
docker compose up -d gitea
docker compose logs -f gitea

Vous devriez voir Gitea démarrer et répondre de nouveau. S’il ne démarre pas, le journal nomme le paramètre ou la migration en cause; remettez l’ancienne étiquette et restaurez la sauvegarde si vous devez revenir en arrière.

Le raccourci : le faire avec Railyard

Les étapes 2 à 5, c’est ce que le modèle Gitea de Railyard fait pour vous : déployer Gitea sur Railyard. Railyard construit Gitea à partir de son dépôt avec son propre Dockerfile, le fait tourner sur un serveur qui vous appartient et lui donne une adresse HTTPS. Vous pouvez ajouter votre propre domaine depuis l’onglet Domains de l’application (Domaines et HTTPS). Vous terminez ensuite le même assistant d’installation qu’à l’étape 6 à l’adresse de l’application : mettez l’adresse HTTPS de l’application dans Gitea Website URL et créez le compte administrateur.

Deux choses à régler avant de créer des dépôts :

• Garder /data sur un volume. Le modèle n’en attache pas, donc ajoutez data:/data sous Volumes dans les paramètres de l’application. Les volumes sont conservés d’un déploiement à l’autre, et vous pouvez en sauvegarder un avec railyard volume:backup <app> data.
• Choisir la base de données. Le modèle n’attache aucun module de base de données, donc Gitea utilise SQLite dans /data. Si vous préférez Postgres, ajoutez-le d’abord depuis l’onglet Resources de l’application et entrez son hôte, son nom, son utilisateur et son mot de passe dans la section base de données de l’assistant, parce que changer de base une fois les dépôts créés demande plus de travail. Les sauvegardes Postgres de Railyard sont décrites dans Bases de données et sauvegardes.

Railyard publie le port web de Gitea en HTTPS, donc sur Railyard, vous clonez et envoyez par HTTPS plutôt que par SSH. Le forfait gratuit de Railyard couvre un serveur plus un serveur de bases de données et trois applications, sans carte. Pro coûte 19 $ US/mois et Team 49 $ US/mois, par équipe.

Dépannage

address already in use sur le port 80, 443 ou 222. Trouvez ce qui écoute avec ss -tlnp | grep -E ':(80|443|222)\s'. Pour le 222, vous pouvez choisir un autre port sur l’hôte (2222:22, par exemple) tant que GITEA__server__SSH_PORT y correspond.

Les adresses de clonage montrent le mauvais hôte, le mauvais port ou http://. Gitea écrit ces paramètres dans /data/gitea/conf/app.ini. Vérifiez ROOT_URL, DOMAIN, SSH_DOMAIN et SSH_PORT dans l’environnement, recréez le conteneur avec docker compose up -d gitea et confirmez que les valeurs ont changé dans app.ini.

Caddy n’obtient pas de certificat. Vérifiez que dig +short git.example.com renvoie l’adresse IP de votre serveur et que le port 80 est ouvert dans le pare-feu de votre fournisseur, puisque Let’s Encrypt valide par ce port. Caddy réessaie tout seul une fois le DNS correct.

Permission denied (publickey) au clonage SSH. Assurez-vous que la clé est ajoutée dans Gitea (pas dans le authorized_keys du serveur), que vous vous connectez au port 222 avec la forme ssh://, et que l’utilisateur est git, pas votre nom d’utilisateur Gitea.

gitea dump indique que Gitea ne doit pas tourner en root. Vous avez oublié -u git. docker compose exec s’exécute en root si vous ne précisez rien.

Le serveur manque de mémoire. Gitea est petit au repos, mais cloner ou envoyer un très gros dépôt peut faire grimper la mémoire. Vérifiez avec dmesg | grep -i "out of memory" et docker stats, et agrandissez le serveur si ça se reproduit.

FAQ

SQLite suffit-il, ou faut-il Postgres? SQLite convient à une petite équipe. La documentation Docker de Gitea inclut une variante Postgres : ajoutez un service db et définissez GITEA__database__DB_TYPE=postgres, GITEA__database__HOST=db:5432, GITEA__database__NAME, GITEA__database__USER et GITEA__database__PASSWD sur le service Gitea. Décidez-le avant la première installation, parce que l’assistant écrit ce choix dans app.ini.

Puis-je apporter mes dépôts de GitHub ou GitLab? Oui. La page New Migration de Gitea a des importateurs pour GitHub, GitLab, Gitea et d’autres services, plus une option Git simple pour n’importe quelle adresse. Les importateurs propres à un service peuvent apporter plus que le code, comme les tickets et les versions, selon la source.

Gitea a-t-il une intégration continue comme GitHub Actions? Gitea Actions utilise des fichiers de flux de travail proches de la syntaxe de GitHub Actions, et les exécute sur un exécuteur distinct que vous installez vous-même. Installer cet exécuteur dépasse ce guide.

Pourquoi le port 222? Il garde la connexion SSH du serveur sur le 22. N’importe quel port libre fonctionne si SSH_PORT correspond au côté hôte de la correspondance.

Un serveur Git auto-hébergé se résume surtout à trois choses : les bonnes adresses dans app.ini, un port SSH qui n’entre pas en conflit avec le vôtre, et une sauvegarde que vous avez vraiment restaurée. Réglez-les dès le premier jour et Gitea s’occupe pratiquement du reste.