forgejo-deploy/README.md

# Déploiement Forgejo depuis les sources avec Ansible

Projet Ansible complet pour déployer [Forgejo](https://forgejo.org) (forge Git auto-hébergée) sur des serveurs Linux, avec compilation depuis les sources et pipeline CI/CD intégré.

## Qu'est-ce que Forgejo ?

Forgejo est une forge Git libre et auto-hébergée (fork communautaire de Gitea). Il permet d'héberger vos dépôts Git, gérer les pull requests, issues, CI/CD, packages, etc. C'est une alternative open-source à GitHub, GitLab ou Bitbucket.

## Caractéristiques de ce projet

- ✅ **Compilation depuis les sources** - Contrôle total sur la version et les options
- ✅ **Installation automatique de Go** (1.22.2) et Node.js (20.x)
- ✅ **CI/CD intégré** - Forgejo Actions avec runner configuré
- ✅ **Base de données SQLite** - Aucune dépendance externe
- ✅ **Service systemd** - Démarrage automatique au boot
- ✅ **Idempotent** - Réexécution sans risque
- ✅ **Multi-serveurs** - Déploiement sur plusieurs machines
- ✅ **Makefile complet** - Commandes simples et intuitives

## Prérequis

### Sur votre machine locale (de contrôle)
- Python 3.8 ou supérieur
- Git
- Connexion internet

### Sur le(s) serveur(s) cible(s)
- Ubuntu 20.04+ ou Debian 11+ (autres distributions non testées)
- Minimum 2 Go RAM, 2 CPU cores
- 10 Go d'espace disque libre
- Accès root via SSH avec clé
- Ports ouverts : 3000 (HTTP), 2222 (SSH Git)

## Installation rapide

```bash
# 1. Générer le projet
python3 create_forgejo_project.py
cd forgejo-deploy

# 2. Installer les dépendances
make install
make install-collections

# 3. Configurer le serveur cible
make setup
# Vous serez invité à saisir :
#   - IP du serveur
#   - Chemin de la clé SSH
#   - Utilisateur SSH (défaut: root)

# 4. Tester la connexion
make test-connection

# 5. Déployer
make deploy
```

**Ou tout en une commande** :
```bash
python3 create_forgejo_project.py && cd forgejo-deploy && make prod
```

## Guide d'installation détaillé

### Étape 1 : Générer le projet

```bash
# Générer avec le nom par défaut
python3 create_forgejo_project.py

# Ou avec un nom personnalisé
python3 create_forgejo_project.py --project-name ma-forge
```

Cela crée un répertoire contenant :
```
forgejo-deploy/
├── Makefile              # Commandes make
├── playbook.yml          # Playbook Ansible principal
├── ansible.cfg           # Configuration Ansible
├── roles/
│   └── forgejo/          # Rôle de déploiement
├── scripts/
└── README.md
```

### Étape 2 : Installer les prérequis

```bash
cd forgejo-deploy

# Crée un virtualenv et installe Ansible
make install

# Installe les collections Ansible nécessaires
make install-collections
```

### Étape 3 : Configurer l'inventaire

```bash
make setup
```

Vous serez invité à saisir :
- **IP du serveur** : L'adresse IP de votre serveur (ex: 192.168.1.100)
- **Clé SSH** : Chemin vers votre clé privée (défaut: ~/.ssh/id_rsa)
- **Utilisateur SSH** : Utilisateur pour la connexion (défaut: root)

Cela crée le fichier `inventory.ini` :
```ini
[forgejo_servers]
forgejo_prod ansible_host=192.168.1.100 ansible_user=root ansible_ssh_private_key_file=/home/user/.ssh/id_rsa

[forgejo_servers:vars]
ansible_python_interpreter=/usr/bin/python3
```

### Étape 4 : Tester la connexion

```bash
make test-connection
```

Si le test échoue, vérifiez :
- L'IP du serveur est correcte
- La clé SSH a les bonnes permissions (`chmod 600 ~/.ssh/id_rsa`)
- L'utilisateur a les droits sudo/root
- Le pare-feu autorise SSH (port 22)

### Étape 5 : Déployer Forgejo

```bash
make deploy
```

Le déploiement prend environ 10-15 minutes et effectue :
1. Installation des dépendances système
2. Installation de Node.js 20.x
3. Installation de Go 1.22.2
4. Création de l'utilisateur système `git`
5. Clonage du code source Forgejo
6. Compilation (backend Go + frontend Node.js)
7. Configuration du service systemd
8. Installation du runner CI/CD
9. Démarrage des services

### Étape 6 : Accéder à Forgejo

Une fois le déploiement terminé :

```bash
# Vérifier que le service tourne
make status

# Consulter les logs si besoin
make logs
```

Accédez à Forgejo via votre navigateur :
```
http://<IP_SERVEUR>:3000
```

**Première connexion** :
- Utilisateur : `admin`
- Mot de passe : `ChangeMe123!`

**Important** : Changez immédiatement le mot de passe admin après la première connexion.

## Commandes disponibles

Toutes les commandes disponibles via `make` :

```bash
make help                # Affiche toutes les commandes
make install            # Installe les prérequis Python/Ansible
make install-collections # Installe les collections Ansible
make check              # Vérifie la syntaxe du playbook
make setup              # Configure l'inventaire (IP + clé SSH)
make test-connection    # Test la connexion SSH au serveur
make deploy             # Déploie Forgejo complet
make deploy-ci          # Déploie uniquement le pipeline CI/CD
make prod               # Installation complète (install + deploy)
make status             # Vérifie le statut du service Forgejo
make logs               # Affiche les logs du service
make update-forgejo     # Met à jour Forgejo vers une nouvelle version
make backup             # Crée une sauvegarde de Forgejo
make clean              # Nettoie les fichiers générés (venv, inventory)
```

## Configuration avancée

### Personnaliser les variables

Éditez `roles/forgejo/defaults/main.yml` pour modifier :

```yaml
# Version de Forgejo
forgejo_version: "8.0.3"

# Ports
forgejo_port: 3000        # Port HTTP
forgejo_ssh_port: 2222    # Port SSH Git

# Répertoires
forgejo_home: "/opt/forgejo"
forgejo_data_dir: "/var/lib/forgejo"

# Utilisateur
forgejo_user: "git"
forgejo_group: "git"

# Credentials admin (à changer !)
forgejo_admin_user: "admin"
forgejo_admin_password: "VotreMotDePasseSecurisé"
forgejo_admin_email: "admin@example.com"

# Base de données
forgejo_db_type: "sqlite3"  # Ou "postgres", "mysql"

# CI/CD
forgejo_enable_actions: true
```

Après modification, redéployez :
```bash
make deploy
```

### Déployer sur plusieurs serveurs

Éditez `inventory.ini` pour ajouter plusieurs serveurs :

```ini
[forgejo_servers]
forge-prod ansible_host=192.168.1.10 ansible_user=root ansible_ssh_private_key_file=~/.ssh/id_rsa
forge-staging ansible_host=192.168.1.20 ansible_user=root ansible_ssh_private_key_file=~/.ssh/id_rsa
forge-dev ansible_host=192.168.1.30 ansible_user=root ansible_ssh_private_key_file=~/.ssh/id_rsa
```

Déployer sur tous :
```bash
make deploy
```

Déployer sur un seul :
```bash
venv/bin/ansible-playbook -i inventory.ini playbook.yml --limit forge-staging
```

### Utiliser PostgreSQL au lieu de SQLite

Dans `roles/forgejo/defaults/main.yml` :

```yaml
forgejo_db_type: "postgres"
forgejo_db_host: "localhost"
forgejo_db_name: "forgejo"
forgejo_db_user: "forgejo"
forgejo_db_password: "VotreMotDePasse"
```

Ajoutez l'installation de PostgreSQL dans les tâches si nécessaire.

## Utilisation du CI/CD

### Activer Forgejo Actions dans un dépôt

Créez `.forgejo/workflows/ci.yml` dans votre dépôt :

```yaml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run tests
        run: |
          echo "Running tests..."
          # Vos commandes de test ici          
      
      - name: Build
        run: |
          echo "Building..."
          # Vos commandes de build ici          
```

Le runner Forgejo exécutera automatiquement ce workflow à chaque push.

### Exemples de workflows

**Python** :
```yaml
name: Python CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install -r requirements.txt
      - run: pytest
```

**Node.js** :
```yaml
name: Node.js CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install
      - run: npm test
```

## Maintenance

### Mettre à jour Forgejo

```bash
# Éditer la version dans roles/forgejo/defaults/main.yml
forgejo_version: "8.1.0"  # Nouvelle version

# Redéployer
make deploy
```

### Sauvegardes

```bash
# Créer une sauvegarde
make backup
```

Pour une sauvegarde complète manuelle :
```bash
ssh root@<ip_serveur>
tar -czf /root/forgejo-backup-$(date +%Y%m%d).tar.gz   /var/lib/forgejo   /opt/forgejo/forgejo   /etc/systemd/system/forgejo.service
```

### Consulter les logs

```bash
# Via make
make logs

# Directement sur le serveur
ssh root@<ip_serveur>
journalctl -u forgejo -f          # Logs en temps réel
journalctl -u forgejo -n 100      # 100 dernières lignes
journalctl -u forgejo-runner -f   # Logs du runner CI/CD
```

### Redémarrer le service

```bash
ssh root@<ip_serveur>
systemctl restart forgejo
systemctl status forgejo
```

## Dépannage

### Le déploiement échoue lors de la compilation

**Erreur** : `node: not found`

**Solution** : Assurez-vous que Node.js est installé. Regénérez le projet avec la dernière version du script.

**Erreur** : `Go version too old`

**Solution** : Le playbook installe automatiquement Go 1.22.2. Si l'erreur persiste, supprimez `/usr/local/go` sur le serveur et relancez.

### Le service ne démarre pas

```bash
# Vérifier les logs
make logs

# Vérifier la configuration
ssh root@<ip_serveur>
/opt/forgejo/forgejo doctor check --all

# Vérifier les permissions
ls -la /opt/forgejo
ls -la /var/lib/forgejo
```

### Impossible de se connecter

**Port 3000 non accessible** :

```bash
# Sur le serveur, vérifier que le service écoute
ss -tlnp | grep 3000

# Vérifier le pare-feu
ufw status
# Autoriser le port si nécessaire
ufw allow 3000/tcp
```

### Erreur "dubious ownership in repository"

```bash
# Sur le serveur
git config --global --add safe.directory /opt/forgejo/src
chown -R git:git /opt/forgejo/src
```

### Le runner CI/CD ne fonctionne pas

```bash
# Vérifier le statut du runner
ssh root@<ip_serveur>
systemctl status forgejo-runner

# Voir les logs
journalctl -u forgejo-runner -n 50
```

## Architecture technique

### Structure des fichiers

```
Serveur Forgejo :
/opt/forgejo/
├── forgejo           # Binaire principal
├── src/              # Code source
└── go/               # GOPATH

/var/lib/forgejo/
├── forgejo.db        # Base de données SQLite
├── repositories/     # Dépôts Git
├── actions/          # Données CI/CD
├── custom/
│   └── conf/
│       └── app.ini   # Configuration
└── runners/          # Configuration runner

/var/log/forgejo/     # Logs
```

### Services systemd

- `forgejo.service` - Service principal Forgejo
- `forgejo-runner.service` - Runner pour CI/CD

### Ports utilisés

- `3000` - Interface web HTTP
- `2222` - SSH Git (pour git clone/push)
- `22` - SSH système (administration)

### Technologies

- **Backend** : Go 1.22.2
- **Frontend** : Node.js 20.x, npm
- **Base de données** : SQLite 3 (par défaut)
- **CI/CD** : Forgejo Actions (compatible GitHub Actions)
- **Orchestration** : Ansible 2.10+
- **OS** : Systemd-based Linux

## Sécurité

### Recommandations post-installation

1. **Changez le mot de passe admin** immédiatement après l'installation

2. **Configurez HTTPS** avec un reverse proxy (nginx/caddy) :
```nginx
server {
    listen 443 ssl http2;
    server_name git.example.com;
    
    ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost: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;
    }
}
```

3. **Configurez le pare-feu** :
```bash
ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP (redirect vers HTTPS)
ufw allow 443/tcp   # HTTPS
ufw allow 2222/tcp  # SSH Git
ufw enable
```

4. **Activez les sauvegardes automatiques** :
```bash
# Cron quotidien
0 2 * * * tar -czf /backup/forgejo-$(date +\%Y\%m\%d).tar.gz /var/lib/forgejo
```

5. **Désactivez l'inscription publique** si non nécessaire (dans `app.ini`) :
```ini
[service]
DISABLE_REGISTRATION = true
```

6. **Activez 2FA** pour les comptes administrateurs

## FAQ

**Q : Puis-je utiliser MySQL/PostgreSQL au lieu de SQLite ?**  
R : Oui, modifiez les variables dans `roles/forgejo/defaults/main.yml` et ajoutez l'installation du serveur de base de données.

**Q : Combien de temps prend le déploiement ?**  
R : Environ 10-15 minutes (compilation comprise).

**Q : Puis-je déployer plusieurs instances Forgejo ?**  
R : Oui, ajoutez plusieurs serveurs dans `inventory.ini`.

**Q : Comment migrer depuis Gitea ?**  
R : Forgejo est un fork de Gitea et est compatible. Copiez simplement les données.

**Q : Forgejo Actions est-il compatible avec GitHub Actions ?**  
R : Oui, la plupart des workflows GitHub Actions fonctionnent sans modification.

**Q : Puis-je utiliser ce script en production ?**  
R : Oui, mais ajoutez HTTPS, des sauvegardes automatiques et durcissez la sécurité.

**Q : Comment contribuer à ce projet ?**  
R : Les pull requests sont bienvenues ! Voir CONTRIBUTING.md.

## Ressources

- [Documentation officielle Forgejo](https://forgejo.org/docs/)
- [Documentation Forgejo Actions](https://forgejo.org/docs/latest/user/actions/)
- [Code source Forgejo](https://codeberg.org/forgejo/forgejo)
- [Forum communautaire](https://codeberg.org/forgejo/discussions)

## Licence

Ce projet de déploiement est sous licence MIT.

Forgejo lui-même est sous licence MIT : https://codeberg.org/forgejo/forgejo/src/branch/forgejo/LICENSE

## Auteur

Généré par create_forgejo_project.py - Projet de déploiement Ansible pour Forgejo

## Support

Pour toute question ou problème :
- Ouvrez une issue dans le dépôt
- Consultez la documentation Forgejo officielle
- Rejoignez la communauté Forgejo

---

**Note importante sur l'intervention humaine** : Ce système nécessite **toujours** une intervention humaine pour déclencher un déploiement. Aucun déploiement automatique n'est effectué. Chaque commande `make deploy` est un acte délibéré et conscient de l'opérateur.