Déploiement Forgejo depuis les sources avec Ansible

Projet Ansible complet pour déployer Forgejo (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

# 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 :

python3 create_forgejo_project.py && cd forgejo-deploy && make prod

Guide d'installation détaillé

Étape 1 : Générer le projet

# 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

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

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 :

[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

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

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é :

# 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 :

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 :

# 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 :

make deploy

Déployer sur plusieurs serveurs

Éditez inventory.ini pour ajouter plusieurs serveurs :

[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 :

make deploy

Déployer sur un seul :

venv/bin/ansible-playbook -i inventory.ini playbook.yml --limit forge-staging

Utiliser PostgreSQL au lieu de SQLite

Dans roles/forgejo/defaults/main.yml :

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 :

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 :

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 :

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

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

# Redéployer
make deploy

Sauvegardes

# Créer une sauvegarde
make backup

Pour une sauvegarde complète manuelle :

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

# 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

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

# 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 :

# 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"

# 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

# 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) :

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 :

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 :

# 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) :

[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
• Documentation Forgejo Actions
• Code source Forgejo
• Forum communautaire

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.