Gitea LFS et stockage MinIO : configuration (2026)

Introduction

Vous venez d’installer Gitea sur votre VPS à Dakar, Abidjan ou Lomé, et tout fonctionne à merveille pour le code source. Puis arrive le premier problème concret : un designer pousse un fichier de maquette Penpot exporté en SVG de 80 Mo, un développeur agritech versionne un jeu de données CSV de 200 Mo, et soudain Gitea répond par un timeout ou un message d’erreur cryptique sur la taille maximale des objets. Git n’est tout simplement pas conçu pour stocker des binaires lourds — il les intègre intégralement dans l’historique, ce qui fait exploser la taille du dépôt et ralentit chaque git clone à chaque nouveau fichier ajouté.

La solution standard dans l’écosystème Git s’appelle Git LFS (Large File Storage). Au lieu de stocker le fichier binaire directement dans le dépôt, Git LFS le remplace par un pointeur texte de quelques dizaines d’octets, et charge le fichier réel sur un serveur dédié au moment du checkout. Gitea implémente le protocole LFS nativement depuis la version 1.x, et peut déléguer le stockage des objets LFS à n’importe quel backend S3-compatible — dont MinIO, un serveur de stockage objet open source que vous pouvez héberger vous-même avec un simple conteneur Docker.

Ce tutoriel vous guide en sept étapes concrètes, de zéro à un Gitea fonctionnel avec LFS stocké sur MinIO. Durée estimée : 25 minutes sur un VPS déjà configuré avec Docker.

Prérequis

• Gitea ou Forgejo déjà installé (version 1.17+ recommandée pour la section [lfs] autonome)
• Docker Engine 24+ et Docker Compose v2 installés sur le même serveur ou sur un serveur dédié
• Accès en écriture au fichier app.ini de Gitea (typiquement /etc/gitea/app.ini ou /data/gitea/conf/app.ini en Docker)
• Git LFS installé sur votre machine cliente (git lfs version pour vérifier)
• Un nom de domaine ou une adresse IP pour MinIO accessible depuis le serveur Gitea (peut être localhost si tout est sur la même machine)
• Niveau : intermédiaire — vous savez éditer un fichier de configuration Linux et exécuter des commandes Docker
• Temps estimé : 20 à 25 minutes

Étape 1 — Pourquoi déporter Git LFS sur MinIO

Avant de toucher la moindre configuration, il est important de comprendre pourquoi cette architecture en deux composants vaut le détour par rapport au stockage LFS local par défaut.

Par défaut, quand vous activez LFS dans Gitea, les objets sont stockés dans un répertoire local sur le même disque que le reste des données Gitea — typiquement data/lfs/. Cette approche fonctionne tant que vous avez un seul serveur et que les fichiers sont raisonnablement petits. Mais elle présente trois limites critiques pour une PME en croissance :

Premièrement, la scalabilité : un disque local est difficile à agrandir sans interruption de service. Avec MinIO, vous pouvez ajouter de l’espace à chaud ou migrer vers un cluster distribué sans toucher à Gitea. Deuxièmement, la séparation des préoccupations : les sauvegardes des binaires LFS (potentiellement des dizaines de gigaoctets) doivent suivre une stratégie différente de celle du code source. En les isolant dans MinIO, vous pouvez appliquer des politiques de rétention, de versioning et de réplication spécifiques. Troisièmement, la résilience : si votre serveur Gitea tombe, vos objets LFS restent accessibles sur MinIO, ce qui simplifie la procédure de restauration.

MinIO est aujourd’hui la référence du stockage objet self-hosted. Il implémente l’intégralité de l’API S3 d’Amazon, ce qui signifie que tout outil conçu pour AWS S3 fonctionne avec MinIO sans modification. Gitea utilise précisément cette API pour déporter ses objets LFS, ses pièces jointes et ses packages. En Afrique de l’Ouest, héberger MinIO localement élimine aussi les coûts de transfert vers AWS S3 ou Google Cloud Storage — un argument non négligeable quand la bande passante internationale reste chère.

Étape 2 — Déployer MinIO via Docker

La manière la plus rapide et la plus reproductible de lancer MinIO est d’utiliser Docker avec un fichier Compose. Cela garantit que les variables d’environnement, les volumes et les ports sont documentés dans un fichier versionnable, et que le redémarrage automatique est géré par Docker lui-même.

Créez un répertoire dédié, par exemple /opt/minio, puis placez-y le fichier suivant :

# /opt/minio/docker-compose.yml
version: "3.9"

services:
  minio:
    image: quay.io/minio/minio:latest
    container_name: minio
    restart: unless-stopped
    ports:
      - "9000:9000"   # API S3 — utilisé par Gitea
      - "9001:9001"   # Console web MinIO
    environment:
      MINIO_ROOT_USER: "admin"         # À remplacer par un nom robuste
      MINIO_ROOT_PASSWORD: "ChangezMoi2026!"  # Minimum 8 caractères
    volumes:
      - /opt/minio/data:/data
    command: server /data --console-address ":9001"

L’image officielle est publiée sur quay.io/minio/minio (registre de Red Hat, miroir de Docker Hub). Le port 9000 est celui que Gitea interrogera pour stocker et récupérer les objets LFS — c’est le point d’entrée de l’API S3. Le port 9001 expose la console web d’administration, accessible depuis votre navigateur pour créer des buckets et des clés d’accès de manière visuelle. Le flag --console-address ":9001" est indispensable : sans lui, MinIO choisit un port aléatoire pour la console à chaque démarrage.

Lancez le service avec la commande suivante :

cd /opt/minio
docker compose up -d

Vérifiez que le conteneur est bien démarré avec docker compose ps : vous devez voir le statut running. Accédez ensuite à http://IP-DU-SERVEUR:9001 depuis votre navigateur — la console MinIO s’affiche avec un formulaire de connexion. Entrez les identifiants définis dans MINIO_ROOT_USER et MINIO_ROOT_PASSWORD. Si la console ne charge pas, vérifiez que votre pare-feu autorise le port 9001 (ufw allow 9001 sur Ubuntu).

Étape 3 — Créer le bucket gitea-lfs et une clé d’accès dédiée

Il est mauvaise pratique de configurer Gitea avec les identifiants root de MinIO. À la place, vous allez créer un bucket dédié et un compte de service (service account) avec des droits limités à ce seul bucket. Cette séparation des privilèges protège vos autres données MinIO si les identifiants Gitea venaient à être compromis.

Installez d’abord le client en ligne de commande MinIO, appelé mc, sur votre serveur :

# Sur Linux x86_64
curl -O https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc
mv mc /usr/local/bin/

Une fois installé, configurez un alias pointant vers votre instance MinIO locale. Cet alias sert de raccourci pour toutes les commandes mc suivantes :

mc alias set local-minio http://localhost:9000 admin ChangezMoi2026!

La commande mc alias set enregistre les informations de connexion dans ~/.mc/config.json. Si vous obtenez une réponse du type Added `local-minio` successfully, la connexion fonctionne. Vérifiez en listant les buckets existants avec mc ls local-minio — la liste doit être vide pour l’instant.

Créez maintenant le bucket dédié à LFS :

mc mb local-minio/gitea-lfs

Puis créez un service account (clé d’accès) dédié à Gitea. Dans la console web (port 9001), naviguez vers Identity → Service Accounts → Create Service Account. Donnez-lui un nom explicite comme gitea-lfs-sa, puis restreignez sa politique au seul bucket gitea-lfs en ajoutant la politique JSON suivante dans le champ « Policy » :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:*"],
      "Resource": [
        "arn:aws:s3:::gitea-lfs",
        "arn:aws:s3:::gitea-lfs/*"
      ]
    }
  ]
}

Après validation, la console affiche une Access Key et une Secret Key — notez-les immédiatement, elles ne seront plus accessibles ensuite. Ce sont ces deux valeurs que vous utiliserez dans la configuration Gitea à l’étape suivante. En ne donnant accès qu’au bucket gitea-lfs, vous vous assurez que même si ces identifiants sont divulgués, aucun autre bucket MinIO n’est exposé.

Étape 4 — Configurer Gitea app.ini, section [lfs]

C’est l’étape centrale du tutoriel. Gitea lit toute sa configuration depuis le fichier app.ini, et la section [lfs] — combinée avec la section [server] — contrôle entièrement le comportement du stockage LFS.

Ouvrez votre app.ini (chemin habituel : /etc/gitea/app.ini en installation native, /data/gitea/conf/app.ini en Docker) avec votre éditeur habituel. Localisez ou créez les sections suivantes :

[server]
; Active le serveur LFS intégré de Gitea
; Requis : Git >= 2.1.2 sur le serveur
LFS_START_SERVER = true

; Durée de validité des tokens JWT d'authentification LFS
LFS_HTTP_AUTH_EXPIRY = 24h

; Taille maximale d'un objet LFS accepté (0 = illimité)
; Exemple : 2147483648 = 2 Go
LFS_MAX_FILE_SIZE = 0

[lfs]
; Déporte le stockage LFS vers MinIO plutôt que le disque local
STORAGE_TYPE           = minio

; Endpoint de votre instance MinIO
; Si Gitea et MinIO sont sur le même serveur, utilisez localhost:9000
; Si MinIO est sur un serveur séparé, utilisez son IP ou nom de domaine
MINIO_ENDPOINT         = localhost:9000

; Access Key et Secret Key du service account créé à l'étape 3
MINIO_ACCESS_KEY_ID    = VOTRE_ACCESS_KEY_ICI
MINIO_SECRET_ACCESS_KEY = VOTRE_SECRET_KEY_ICI

; Nom du bucket créé à l'étape 3
MINIO_BUCKET           = gitea-lfs

; Région — laisser "us-east-1" même pour MinIO self-hosted
; MinIO accepte n'importe quelle valeur ici
MINIO_LOCATION         = us-east-1

; false si MinIO est en HTTP local (sans certificat TLS)
; true si MinIO est derrière un reverse proxy HTTPS
MINIO_USE_SSL          = false

; Optionnel : sous-répertoire dans le bucket
MINIO_BASE_PATH        = lfs/

Une fois les modifications sauvegardées, redémarrez Gitea pour qu’elles prennent effet. En installation native : systemctl restart gitea. En Docker : docker restart gitea (ou docker compose restart si vous utilisez Compose). Attendez 10 secondes, puis vérifiez les logs pour détecter d’éventuelles erreurs de connexion à MinIO : docker logs gitea --tail 50 ou journalctl -u gitea -n 50. L’absence d’erreur minio ou lfs dans les logs indique que la connexion s’est établie correctement.

Un point important sur la sécurité : si MinIO est exposé sur Internet (et non sur localhost), activez HTTPS devant MinIO via un reverse proxy Nginx ou Caddy, et passez MINIO_USE_SSL = true dans Gitea. Les identifiants LFS transiteraient sinon en clair sur le réseau.

Étape 5 — Test client : git lfs install et push d’un fichier de 100 Mo

La configuration serveur est en place. Il est maintenant temps de valider que le pipeline fonctionne de bout en bout, depuis votre machine cliente jusqu’au bucket MinIO, en passant par Gitea.

Sur votre machine de développement, assurez-vous que Git LFS est installé. Sur Ubuntu/Debian : sudo apt install git-lfs. Sur macOS : brew install git-lfs. Sur Windows, le package est inclus dans Git for Windows depuis la version 2.36. Vérifiez avec :

git lfs version
# Sortie attendue : git-lfs/3.x.x (GitHub; linux amd64; go 1.2x)

Clonez un dépôt de test depuis votre Gitea (ou créez-en un nouveau via l’interface web). Puis activez LFS dans le dépôt local et déclarez le type de fichiers à tracker :

# Initialiser LFS pour ce dépôt (crée le hook pre-push)
git lfs install

# Déclarer que les fichiers .bin seront gérés par LFS
git lfs track "*.bin"
git lfs track "*.psd"
git lfs track "*.mp4"

# Toujours committer .gitattributes en premier
git add .gitattributes
git commit -m "chore: activer Git LFS pour les binaires"

La commande git lfs track ajoute une ligne dans le fichier .gitattributes à la racine du dépôt. Ce fichier indique à Git LFS quels patterns de fichiers doivent être interceptés. Il est crucial de le committer avant d’ajouter des fichiers binaires, sans quoi ces fichiers seraient stockés directement dans Git.

Créez maintenant un fichier de test de 100 Mo pour simuler un binaire réel :

# Génère un fichier aléatoire de 100 Mo
dd if=/dev/urandom of=test-asset.bin bs=1M count=100

git add test-asset.bin
git commit -m "test: ajouter binaire 100Mo via LFS"
git push origin main

Pendant le push, vous verrez une sortie supplémentaire caractéristique de Git LFS :

Uploading LFS objects: 100% (1/1), 105 MB | 12 MB/s, done.

Cette ligne confirme que le fichier a bien été transmis au serveur LFS de Gitea, qui l’a ensuite stocké dans votre bucket MinIO. Pour le vérifier côté serveur, retournez dans la console MinIO (port 9001), naviguez vers le bucket gitea-lfs et vous devez y voir un objet dont le nom est un hash SHA-256. Vous pouvez aussi utiliser mc ls local-minio/gitea-lfs/ --recursive pour lister les objets en ligne de commande. Si l’objet est là, le pipeline est entièrement fonctionnel.

Étape 6 — Gestion des quotas par utilisateur

La gestion des quotas LFS dans Gitea 2026 s’opère à deux niveaux complémentaires, et il est important de bien comprendre la frontière de responsabilité entre Gitea et MinIO.

Du côté Gitea, la clé LFS_MAX_FILE_SIZE dans la section [server] de app.ini définit la taille maximale d’un objet LFS individuel, en octets. Mettre cette valeur à 2147483648 (2 Go) bloque tout push d’un fichier unique dépassant ce seuil, quelle que soit l’identité de l’utilisateur. C’est un garde-fou global utile pour éviter qu’un utilisateur distrait tente de pusher une image disque virtuelle de 10 Go. La valeur 0 signifie illimité.

Pour un contrôle plus fin par utilisateur ou par équipe, c’est MinIO qui prend le relais via son système de politiques IAM. Vous pouvez créer des service accounts distincts avec des politiques différentes : par exemple, un service account pour les développeurs avec accès complet au bucket gitea-lfs, et un autre pour les contributeurs externes avec une politique de quota intégrée. MinIO supporte également le bucket versioning et les lifecycle policies pour expirer automatiquement les anciens objets et libérer de l’espace.

En pratique pour une PME, la combinaison recommandée est : LFS_MAX_FILE_SIZE = 1073741824 (1 Go par fichier) dans Gitea pour le garde-fou technique, et une politique MinIO par bucket-projet si vous avez plusieurs projets avec des contraintes différentes. Cette architecture évite d’avoir à créer un bucket MinIO distinct par utilisateur — ce qui deviendrait ingérable — tout en conservant un contrôle granulaire au niveau des projets.

Étape 7 — Backup MinIO via mc mirror

Un bucket MinIO contenant vos fichiers LFS doit être sauvegardé avec la même rigueur que votre base de données Gitea. La commande mc mirror du client MinIO est conçue précisément pour cette tâche : elle synchronise le contenu d’un bucket source vers une destination S3-compatible, qu’il s’agisse d’un autre serveur MinIO, d’un bucket AWS S3 ou de tout autre stockage objet.

Pour une sauvegarde quotidienne vers un second serveur MinIO (ou un bucket AWS S3 en dernier recours), commencez par configurer un alias pour la destination :

# Alias vers votre serveur de backup (peut être un autre VPS)
mc alias set backup-minio http://IP-BACKUP:9000 admin-backup MotDePasseBackup!

# Créer le bucket de destination s'il n'existe pas
mc mb backup-minio/gitea-lfs-backup

Puis lancez la synchronisation :

# Synchronisation ponctuelle (sens unique : source → destination)
mc mirror local-minio/gitea-lfs backup-minio/gitea-lfs-backup

# Synchronisation continue avec surveillance des nouveaux fichiers
mc mirror --watch local-minio/gitea-lfs backup-minio/gitea-lfs-backup

Le flag --watch maintient le processus actif et réplique chaque nouvel objet ajouté au bucket source en quasi-temps réel. Pour un environnement de production, l’approche recommandée est de planifier la commande sans --watch via un cron job, ce qui garantit une synchronisation complète à intervalles réguliers sans dépendre d’un processus long-running :

# Cron job : sauvegarde LFS chaque nuit à 2h00
0 2 * * * /usr/local/bin/mc mirror --overwrite local-minio/gitea-lfs backup-minio/gitea-lfs-backup >> /var/log/minio-backup.log 2>&1

Le flag --overwrite garantit que les fichiers modifiés (cas rare avec LFS où les objets sont immuables par design) sont bien remplacés. Vérifiez régulièrement le fichier de log pour détecter d’éventuelles erreurs de connexion ou d’espace disque insuffisant sur la destination.

Erreurs fréquentes

Adaptation au contexte ouest-africain

Pour les équipes en Afrique de l’Ouest, la combinaison Gitea LFS + MinIO self-hosted présente des avantages particulièrement concrets qui méritent d’être explicités.

Le premier avantage est l’économie de bande passante internationale. Quand vous hébergez MinIO sur un VPS à Dakar (chez OVHcloud, Scaleway ou un hébergeur local comme Sonatel Cloud), les développeurs de votre équipe téléchargent les fichiers LFS depuis un serveur géographiquement proche, avec des latences de 5 à 20 ms au lieu de 150 à 300 ms vers AWS eu-west-1. Sur un projet de jeu agritech avec des assets graphiques de plusieurs centaines de mégaoctets, la différence est visible à l’usage quotidien. De plus, vous évitez les frais de transfert sortant d’AWS S3, qui peuvent devenir significatifs au-delà de quelques dizaines de gigaoctets par mois.

Le deuxième avantage concerne les usages spécifiques à l’Afrique de l’Ouest. Les studios de design travaillant avec Penpot (l’alternative open source à Figma, idéale pour les équipes qui veulent s’affranchir des licences SaaS) exportent régulièrement des fichiers SVG complexes, des exports PNG haute résolution ou des prototypes ZIP dépassant les 50 Mo. Ces fichiers n’ont pas leur place dans Git, mais doivent rester versionnés. Git LFS + MinIO local résout exactement ce problème. De même, les startups agritech qui versionnent des jeux de données CSV ou Parquet pour l’entraînement de modèles de prédiction de rendements peuvent utiliser ce pipeline pour garder l’historique des datasets sans saturer leurs dépôts Git.

Troisièmement, la résilience aux coupures de courant et d’Internet. En configurant MinIO sur un NAS local avec une batterie de secours, une équipe peut continuer à pousser des fichiers LFS pendant une coupure d’accès international, puis laisser mc mirror --watch synchroniser automatiquement vers le backup cloud dès la reconnexion. Cette architecture hybride local + cloud est particulièrement adaptée aux contextes où la connectivité internationale est intermittente.

Pour les équipes avec un budget limité, notez que MinIO fonctionne très bien sur un VPS entrée de gamme à 5-10€/mois (2 vCPU, 4 Go RAM, 80 Go SSD) tant que le volume de données LFS reste inférieur à quelques dizaines de gigaoctets. Au-delà, un volume block supplémentaire est souvent plus économique qu’un passage à AWS S3.

Tutoriels frères

• Installer Gitea ou Forgejo sur VPS avec Docker (2026) — mise en place complète de la forge avec reverse proxy Nginx et HTTPS
• Gitea Actions : CI/CD self-hosted pas-à-pas (2026) — automatiser les tests et déploiements avec le runner Gitea Actions
• GitLab CE vs Gitea : quel choix pour une PME ouest-africaine ? (2026) — comparatif fonctionnel et économique pour choisir sa forge

Pour aller plus loin

• Retour au pilier : Forge Git self-hosted pour équipe PME : Gitea, Forgejo, GitLab CE (2026)
• Documentation officielle Gitea LFS : docs.gitea.com/administration/git-lfs-setup
• Documentation MinIO Linux : min.io/docs/minio/linux/
• Référence commande mc mirror : min.io/docs/minio/linux/reference/minio-mc/mc-mirror.html
• Site officiel Git LFS : git-lfs.com
• Prochaine étape dans le cluster : automatiser vos pipelines CI/CD avec Gitea Actions

FAQ

Q : Puis-je utiliser ce tutoriel avec Forgejo plutôt que Gitea ?

Oui, entièrement. Forgejo est un fork de Gitea qui conserve la même structure de fichier app.ini et les mêmes clés de configuration pour LFS. Les sections [server] et [lfs] sont identiques. La seule différence éventuelle concerne les versions mineures et les chemins de données par défaut — vérifiez la documentation de votre version de Forgejo si vous observez un comportement inattendu.

Q : MinIO doit-il être sur le même serveur que Gitea ?

Non, et ce n’est d’ailleurs pas recommandé en production. MinIO peut être sur un serveur distinct, un NAS, ou même un autre datacenter. Il suffit que le serveur Gitea puisse atteindre l’endpoint MinIO sur le port 9000 (API S3). Adaptez la valeur MINIO_ENDPOINT en conséquence — par exemple minio.votredomaine.com:9000 si MinIO est derrière un DNS interne.

Q : Git LFS fonctionne-t-il correctement avec les dépôts miroirs et les forks dans Gitea ?

Les objets LFS ne sont pas automatiquement copiés lors d’un fork dans Gitea — seuls les pointeurs texte sont copiés dans le dépôt Git. Les fichiers binaires restent dans le bucket MinIO et sont partagés par référence via leur hash SHA-256. Cela signifie qu’un fork qui utilise les mêmes objets LFS ne duplique pas les données dans MinIO, ce qui est économique en espace. Pour les miroirs de dépôts externes (GitHub, GitLab), l’import LFS doit être déclenché explicitement via git lfs fetch --all suivi d’un git lfs push --all.

Q : Quelle taille de serveur MinIO est recommandée pour une équipe de 10 développeurs ?

Pour une petite équipe avec des fichiers LFS modérément volumineux (designs, datasets de taille raisonnable), un VPS avec 2 vCPU, 4 Go de RAM et un volume de stockage bloc de 200 à 500 Go est largement suffisant. MinIO lui-même est très léger — il consomme typiquement 200 à 300 Mo de RAM au repos. Le facteur limitant est presque toujours l’espace disque, pas le CPU. Commencez petit et redimensionnez le volume selon la croissance réelle des données.

Q : Comment migrer les objets LFS déjà stockés localement vers MinIO ?

Si vous avez déjà des objets LFS dans le répertoire local de Gitea (typiquement data/lfs/), vous pouvez les migrer vers MinIO en deux étapes. Premièrement, uploadez les fichiers existants dans le bucket MinIO avec mc cp --recursive /chemin/vers/data/lfs/ local-minio/gitea-lfs/. Deuxièmement, mettez à jour app.ini pour pointer vers MinIO et redémarrez Gitea. Gitea calculera les chemins des objets LFS de la même manière (par hash SHA-256) et les trouvera dans MinIO. Conservez l’ancien répertoire local quelques jours avant de le supprimer, le temps de valider que tous les objets sont bien accessibles.

Q : Git LFS ralentit-il les opérations git habituelles comme git status ou git log ?

Non — c’est précisément l’avantage principal de Git LFS. Les commandes git status, git log, git diff et git checkout (sans les fichiers LFS) restent aussi rapides qu’un dépôt sans binaires, car ces fichiers ne sont représentés que par des pointeurs texte de quelques dizaines d’octets dans le dépôt Git lui-même. Le transfert réseau vers MinIO n’intervient qu’au moment d’un git push ou d’un git checkout qui touche effectivement un fichier LFS. Si vous travaillez sur du code pur sans modifier les assets binaires, vous ne verrez aucune différence de performance.

Q : Que se passe-t-il si MinIO est temporairement indisponible ?

Si MinIO est inaccessible au moment d’un git push impliquant des fichiers LFS, le push échoue avec une erreur explicite côté client — le dépôt Git principal n’est pas corrompu. Les commits locaux sont préservés et vous pouvez relancer le push dès que MinIO est à nouveau disponible. Les opérations qui n’impliquent pas de fichiers LFS (push de code pur, création de branches, merge requests) ne sont pas affectées par l’indisponibilité de MinIO.