Restructure project following production-ready standards
- Add comprehensive docker-compose configuration with health checks - Create Makefile with 16 utility commands for easy management - Implement robust backup/restore/update scripts with error handling - Add optimized PostgreSQL configuration for Gitea workload - Enhance .env.example with clear dev/prod sections and documentation - Create comprehensive README with installation, configuration, and maintenance guides - Improve .gitignore to exclude all sensitive and generated files - Add Redis persistence (AOF) and memory limits - Configure service dependencies with health conditions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
BeauTroll
519
README.md
Normal file
519
README.md
Normal file
@@ -0,0 +1,519 @@
|
||||
# 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](#architecture)
|
||||
- [Prérequis](#prérequis)
|
||||
- [Installation](#installation)
|
||||
- [Configuration](#configuration)
|
||||
- [Démarrage](#démarrage)
|
||||
- [Maintenance](#maintenance)
|
||||
- [Sauvegardes](#sauvegardes)
|
||||
- [Restauration](#restauration)
|
||||
- [Mises à jour](#mises-à-jour)
|
||||
- [Commandes Make](#commandes-make)
|
||||
- [Dépannage](#dépannage)
|
||||
- [Sécurité](#sécurité)
|
||||
- [Structure du projet](#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
|
||||
|
||||
```bash
|
||||
git clone <url-du-depot>
|
||||
cd agence66-gitea
|
||||
```
|
||||
|
||||
### 2. Créer le fichier de configuration
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
### 3. Configurer les variables d'environnement
|
||||
|
||||
Éditez le fichier `.env` et modifiez les valeurs :
|
||||
|
||||
```bash
|
||||
nano .env # ou vim, code, etc.
|
||||
```
|
||||
|
||||
**IMPORTANT**: Changez tous les mots de passe par défaut !
|
||||
|
||||
```bash
|
||||
# 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 :
|
||||
|
||||
```env
|
||||
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 :
|
||||
|
||||
```env
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
make health
|
||||
```
|
||||
|
||||
Ou :
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Sauvegardes
|
||||
|
||||
#### Créer une sauvegarde manuelle
|
||||
|
||||
```bash
|
||||
make backup
|
||||
```
|
||||
|
||||
Ou :
|
||||
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```bash
|
||||
crontab -e
|
||||
```
|
||||
|
||||
Ajoutez :
|
||||
|
||||
```cron
|
||||
# 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
|
||||
|
||||
```bash
|
||||
make restore FILE=backups/gitea_backup_20240101_120000.tar.gz
|
||||
```
|
||||
|
||||
Ou :
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
make update
|
||||
```
|
||||
|
||||
Ou :
|
||||
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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** :
|
||||
|
||||
```bash
|
||||
make logs-f
|
||||
```
|
||||
|
||||
Ou :
|
||||
|
||||
```bash
|
||||
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** :
|
||||
|
||||
```bash
|
||||
make shell-db
|
||||
```
|
||||
|
||||
**Vérifier la connexion** :
|
||||
|
||||
```bash
|
||||
docker compose exec db pg_isready -U gitea -d gitea
|
||||
```
|
||||
|
||||
### Problèmes de performance
|
||||
|
||||
**Vérifier l'utilisation des ressources** :
|
||||
|
||||
```bash
|
||||
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** :
|
||||
|
||||
```bash
|
||||
docker compose exec redis redis-cli --raw incr ping
|
||||
```
|
||||
|
||||
### Réinitialisation complète
|
||||
|
||||
**ATTENTION** : Cela supprimera toutes les données !
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
make logs-f
|
||||
```
|
||||
|
||||
### Exposition sécurisée (Production)
|
||||
|
||||
**Avec nginx** :
|
||||
|
||||
```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** :
|
||||
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user