agence66-gitea/README.md

# 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