Daniel Allaire 2b524df212 premier commit du déploiement d'un serveur forgejo.

2025-10-06 18:01:40 -04:00

14 KiB

Raw Permalink Blame History

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 :

Installation des dépendances système
Installation de Node.js 20.x
Installation de Go 1.22.2
Création de l'utilisateur système git
Clonage du code source Forgejo
Compilation (backend Go + frontend Node.js)
Configuration du service systemd
Installation du runner CI/CD
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

Changez le mot de passe admin immédiatement après l'installation
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;
    }
}

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

Activez les sauvegardes automatiques :

# Cron quotidien
0 2 * * * tar -czf /backup/forgejo-$(date +\%Y\%m\%d).tar.gz /var/lib/forgejo

Désactivez l'inscription publique si non nécessaire (dans app.ini) :

[service]
DISABLE_REGISTRATION = true

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

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.

14 KiB Raw Permalink Blame History