Gitea Docker - Instance Auto-hébergée

Déploiement Docker de Gitea avec PostgreSQL et Redis, conçu pour être stable, maintenable et facilement déployable.

Table des matières

• Architecture
• Prérequis
• Installation
• Configuration
• Démarrage
• Maintenance
  • Sauvegardes
  • Restauration
  • Mises à jour
• Commandes Make
• Dépannage
• Sécurité
• Structure du projet

Architecture

Cette installation comprend 3 services Docker orchestrés :

Services

1. Gitea - Serveur Git auto-hébergé

   • Port web: 127.0.0.1:3000 (localhost uniquement)
   • Port SSH: 2223
   • Base de données: PostgreSQL
   • Cache: Redis
   • Health check: API /api/healthz

2. PostgreSQL 15 - Base de données

   • Stockage: ./postgres
   • Configuration personnalisée: ./db-config/postgresql.conf
   • Health check: pg_isready

3. Redis - Cache et sessions

   • Stockage: ./redis (persistence AOF)
   • Limite mémoire: 256MB
   • Politique d'éviction: allkeys-lru

Réseaux

• gitea (bridge) - Réseau interne pour la communication entre services

Prérequis

Logiciels requis

• Docker >= 20.10
• Docker Compose >= 2.0
• Make (optionnel mais recommandé)
• Bash >= 4.0

Ressources matérielles recommandées

Composant	Minimum	Recommandé
CPU	2 cœurs	4+ cœurs
RAM	2 GB	4+ GB
Stockage	10 GB	50+ GB SSD

Système d'exploitation

• Linux (Ubuntu 20.04+, Debian 11+, etc.)
• macOS 10.15+
• Windows 10/11 avec WSL2

Installation

1. Cloner le dépôt

git clone <url-du-depot>
cd agence66-gitea

2. Créer le fichier de configuration

cp .env.example .env

3. Configurer les variables d'environnement

Éditez le fichier .env et modifiez les valeurs :

nano .env  # ou vim, code, etc.

IMPORTANT: Changez tous les mots de passe par défaut !

# Générer des mots de passe sécurisés
openssl rand -base64 32

Configuration

Variables d'environnement

Variable	Description	Exemple
GITEA_DOMAIN	Domaine principal	git.example.com
GITEA_SSH_DOMAIN	Domaine SSH	git.example.com
GITEA_ROOT_URL	URL complète	https://git.example.com
POSTGRES_DATABASE	Nom de la BDD	gitea
POSTGRES_USER	Utilisateur PostgreSQL	gitea
POSTGRES_PASSWORD	Mot de passe BDD	changeme_secure_password_here
REDIS_PASSWORD	Mot de passe Redis	changeme_redis_password_here
BACKUP_RETENTION_DAYS	Rétention des sauvegardes	7

Configuration Développement vs Production

Mode Développement (local)

Dans .env, utilisez :

GITEA_DOMAIN=localhost
GITEA_SSH_DOMAIN=localhost
GITEA_ROOT_URL=http://localhost:3000

Accès :

• Web: http://localhost:3000
• SSH: ssh -p 2223 git@localhost

Mode Production

Dans .env, utilisez :

GITEA_DOMAIN=domain.tld
GITEA_SSH_DOMAIN=domain.tld
GITEA_ROOT_URL=https://domain.tld

IMPORTANT: En production, utilisez un reverse proxy (nginx/traefik) avec SSL/TLS.

Configuration PostgreSQL

La configuration optimisée se trouve dans db-config/postgresql.conf.

Ajustez selon vos ressources :

• shared_buffers: 25% de la RAM disponible
• effective_cache_size: 50-75% de la RAM disponible

Démarrage

Première installation

# Démarrer tous les services
make up

# Ou avec docker compose directement
docker compose up -d

Accéder à Gitea

1. Ouvrez votre navigateur sur http://localhost:3000
2. Suivez l'assistant de configuration initial
3. Créez le premier utilisateur administrateur

Note: La plupart des paramètres sont déjà configurés via les variables d'environnement.

Vérifier l'état des services

make health

Ou :

docker compose ps

Maintenance

Sauvegardes

Créer une sauvegarde manuelle

make backup

Ou :

bash scripts/backup.sh

Contenu de la sauvegarde :

• Base de données PostgreSQL (dump compressé)
• Dépôts Git
• Configuration Gitea
• Données utilisateur

Emplacement : ./backups/gitea_backup_YYYYMMDD_HHMMSS.tar.gz

Rétention automatique

Les sauvegardes de plus de BACKUP_RETENTION_DAYS jours (défaut: 7) sont automatiquement supprimées.

Sauvegardes automatiques (cron)

Ajoutez une tâche cron pour des sauvegardes quotidiennes :

crontab -e

Ajoutez :

# Sauvegarde quotidienne à 3h du matin
0 3 * * * cd /chemin/vers/agence66-gitea && make backup >> /var/log/gitea-backup.log 2>&1

Restauration

Restaurer depuis une sauvegarde

make restore FILE=backups/gitea_backup_20240101_120000.tar.gz

Ou :

bash scripts/restore.sh backups/gitea_backup_20240101_120000.tar.gz

ATTENTION : Cette opération est destructive et écrasera toutes les données actuelles !

Le script vous demandera confirmation avant de procéder.

Processus de restauration

1. Extraction de l'archive
2. Arrêt des services
3. Restauration de la base de données
4. Restauration des fichiers
5. Redémarrage des services

Mises à jour

Mettre à jour Gitea

make update

Ou :

bash scripts/update.sh

Le script effectue :

1. Sauvegarde automatique de sécurité
2. Téléchargement des nouvelles images
3. Arrêt des services
4. Démarrage avec les nouvelles versions
5. Vérification de l'état

En cas de problème, restaurez la sauvegarde créée automatiquement :

make restore FILE=backups/gitea_backup_YYYYMMDD_HHMMSS.tar.gz

Commandes Make

Commande	Description
make help	Afficher l'aide
make up	Démarrer tous les services
make down	Arrêter tous les services
make restart	Redémarrer les services
make ps	Afficher le statut des services
make logs	Afficher les logs (100 dernières lignes)
make logs-f	Suivre les logs en temps réel
make backup	Créer une sauvegarde
make restore FILE=...	Restaurer une sauvegarde
make update	Mettre à jour Gitea
make health	Vérifier la santé des services
make shell-gitea	Ouvrir un shell dans Gitea
make shell-db	Ouvrir un shell PostgreSQL
make clean	Nettoyer les conteneurs arrêtés
make pull	Télécharger les dernières images
make config	Valider la configuration Docker
make stats	Afficher les statistiques de ressources

Créer un utilisateur admin en ligne de commande

make admin-create USER=admin EMAIL=admin@example.com

Le mot de passe par défaut sera ChangeMe123! (à changer immédiatement).

Dépannage

Gitea ne démarre pas

Vérifier les logs :

make logs-f

Ou :

docker compose logs -f gitea

Causes courantes :

• Base de données non prête : attendez que PostgreSQL soit healthy
• Permissions de fichiers : vérifiez ./data (UID/GID 1000)
• Port déjà utilisé : vérifiez si le port 3000 ou 2223 est disponible

Erreurs de base de données

Vérifier PostgreSQL :

make shell-db

Vérifier la connexion :

docker compose exec db pg_isready -U gitea -d gitea

Problèmes de performance

Vérifier l'utilisation des ressources :

make stats

Optimisations :

1. Augmentez shared_buffers dans db-config/postgresql.conf
2. Ajustez la limite mémoire Redis dans docker-compose.yml
3. Activez la compression dans Gitea

Redis ne fonctionne pas

Vérifier Redis :

docker compose exec redis redis-cli --raw incr ping

Réinitialisation complète

ATTENTION : Cela supprimera toutes les données !

make down
sudo rm -rf data/ postgres/ redis/ backups/
make up

Sécurité

Bonnes pratiques

1. Mots de passe forts : Utilisez des mots de passe de 32+ caractères

   openssl rand -base64 32
   

2. Fichier .env : Ne le commitez JAMAIS dans Git (déjà dans .gitignore)

3. Mises à jour régulières : Mettez à jour Gitea régulièrement

   make update
   

4. Reverse proxy : En production, utilisez nginx/traefik avec SSL/TLS

5. Firewall : Limitez l'accès aux ports nécessaires

   • 3000 : Web (via reverse proxy uniquement)
   • 2223 : SSH Git

6. Sauvegardes : Automatisez les sauvegardes et testez la restauration

7. Logs : Surveillez les logs pour détecter les activités suspectes

   make logs-f
   

Exposition sécurisée (Production)

Avec nginx :

server {
    listen 80;
    server_name git.domain.tld;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name git.domain.tld;

    ssl_certificate /etc/letsencrypt/live/git.domain.tld/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.domain.tld/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
    }
}

SSH Git

Le service SSH Gitea est exposé sur le port 2223.

Cloner un dépôt :

git clone ssh://git@domain.tld:2223/username/repository.git

Configuration SSH (~/.ssh/config) :

Host git.domain.tld
    Port 2223
    User git

Après cette configuration :

git clone git@git.domain.tld:username/repository.git

Structure du projet

agence66-gitea/
├── .env                        # Configuration (ne pas committer)
├── .env.example                # Template de configuration
├── .gitignore                  # Fichiers à ignorer par Git
├── docker-compose.yml          # Orchestration Docker
├── Makefile                    # Commandes simplifiées
├── README.md                   # Cette documentation
├── backups/                    # Sauvegardes (généré)
│   └── gitea_backup_*.tar.gz
├── data/                       # Données Gitea (généré)
│   ├── git/                    # Dépôts Git
│   ├── gitea/                  # Configuration Gitea
│   └── ...
├── db-config/                  # Configuration PostgreSQL
│   └── postgresql.conf
├── postgres/                   # Données PostgreSQL (généré)
├── redis/                      # Données Redis (généré)
└── scripts/                    # Scripts de maintenance
    ├── backup.sh               # Sauvegarde complète
    ├── restore.sh              # Restauration
    └── update.sh               # Mise à jour

Support

Problèmes et questions

• Issues GitHub : Créez une issue sur le dépôt
• Documentation Gitea : https://docs.gitea.io/
• Docker : https://docs.docker.com/

Logs utiles

# Tous les logs
make logs

# Logs Gitea uniquement
docker compose logs -f gitea

# Logs PostgreSQL
docker compose logs -f db

# Logs Redis
docker compose logs -f redis

---

Auteur : Agence66 Licence : À définir Version : 1.0.0