Forgejo

Le rôle Forgejo permet d’installer et de configurer Forgejo sur le VPS.

Forgejo est une plateforme libre d’hébergement et de gestion de dépôts Git. Elle permet notamment de :

• centraliser les dépôts Git ;
• gérer les utilisateurs et leurs permissions ;
• suivre l’évolution des projets ;
• gérer les issues et les pull requests ;
• conserver l’historique des modifications ;
• revenir à une version précédente du code si nécessaire ;
• isoler différents développements grâce aux branches ;
• exécuter des pipelines CI/CD grâce aux Forgejo Runners.

L’utilisation de Forgejo permet également de conserver une copie centralisée des projets sur le VPS. En cas de problème sur une machine de développement, les dépôts présents sur le serveur peuvent ainsi être récupérés.

Remarque : Forgejo ne remplace pas une stratégie de sauvegarde. Les dépôts et les données de Forgejo doivent également être sauvegardés afin de pouvoir restaurer le service en cas de perte ou de corruption du VPS.

Fonctionnement

Forgejo est déployé dans un conteneur Docker.

Les images Docker officielles sont disponibles via le projet Forgejo et notamment sur Codeberg.

Le rôle Ansible génère ensuite un fichier docker-compose.yml à partir d’un template Jinja2. Ce fichier décrit le fonctionnement du conteneur Forgejo ainsi que les volumes utilisés pour conserver les données.

Forgejo peut fonctionner avec plusieurs systèmes de gestion de bases de données. Dans cette configuration, si aucune base de données externe n’est configurée, Forgejo utilise SQLite.

SQLite est adaptée à une installation simple ou à faible charge. Pour une infrastructure plus importante, une base de données dédiée comme PostgreSQL peut être privilégiée.

Persistance des données

Les données de Forgejo doivent être stockées dans des volumes ou des répertoires persistants montés dans le conteneur.

Cela permet de conserver les données lors :

• du redémarrage du conteneur ;
• de la recréation du conteneur ;
• de la mise à jour de l’image Docker.

La configuration Docker ne doit donc pas stocker les données uniquement dans le système de fichiers interne du conteneur.

Structure du rôle

roles/forgejo/
├── defaults/
│   └── main.yml                 # Variables par défaut du rôle
├── handlers/
│   └── main.yml                 # Handlers, notamment pour les redémarrages
├── tasks/
│   ├── admin_users.yml          # Création des utilisateurs administrateurs
│   ├── deploy.yml               # Déploiement de Forgejo
│   ├── directories.yml          # Création des répertoires nécessaires
│   ├── main.yml                 # Point d'entrée du rôle
│   ├── register_runner.yml      # Enregistrement des Forgejo Runners
│   ├── start.yml                # Démarrage de Forgejo
│   └── wait.yml                 # Attente du démarrage de Forgejo
└── templates/
    └── docker-compose.yml.j2    # Template Docker Compose de Forgejo

Variables

Les variables du rôle sont définies dans le fichier :

roles/forgejo/defaults/main.yml

Elles permettent notamment de modifier certains paramètres du déploiement sans avoir à modifier directement les tâches Ansible.

Variables globales

Variable	Description
forgejo_image	Image Docker utilisée pour Forgejo
forgejo_domain	Nom de domaine utilisé pour accéder à Forgejo
forgejo_uid	UID utilisé par Forgejo
forgejo_gid	GID utilisé par Forgejo
forgejo_runner_name	Nom du ou des runners utilisés par Forgejo

Les valeurs par défaut peuvent être surchargées depuis les variables d’inventaire ou les variables du playbook.

Déploiement

Lors de l’exécution du rôle, les différentes tâches sont réalisées dans l’ordre nécessaire au fonctionnement de Forgejo.

Le rôle effectue notamment les opérations suivantes :

1. définir les chemins et répertoires nécessaires ;
2. préparer les fichiers de configuration ;
3. déployer le fichier docker-compose.yml ;
4. démarrer le conteneur Forgejo ;
5. attendre que Forgejo soit disponible ;
6. créer ou configurer les utilisateurs administrateurs ;
7. enregistrer les Forgejo Runners ;
8. rendre le service accessible via le domaine configuré.

L’ordre des opérations est important : les utilisateurs et les runners ne peuvent être configurés correctement qu’une fois que Forgejo est démarré et accessible.

Vérifications

Après l’exécution du rôle Ansible, plusieurs vérifications permettent de s’assurer que le déploiement fonctionne correctement.

1. Vérifier que le conteneur Forgejo fonctionne

Afficher les conteneurs actuellement en cours d’exécution :

docker ps

docker logs forgejo --tail 100

2. Vérifier les logs de Forgejo

Commande :

docker logs forgejo --tail 100

Pour suivre les logs en temps réel :

docker logs -f forgejo

3. Vérifier Caddy

Caddy est utilisé comme reverse proxy afin d’exposer Forgejo via son nom de domaine.

Vérifier que la configuration Caddy est valide :

docker exec caddy caddy validate --config /etc/caddy/Caddyfile

Consulter ensuite les logs :

docker logs caddy --tail 100

Ces vérifications permettent notamment de détecter un problème de configuration du reverse proxy ou de certificat TLS.

4. Vérifier l’accès depuis l’extérieur

Depuis le poste de développement, ouvrir le domaine configuré pour Forgejo :

Forgejo

5. Vérifier le fonctionnement de Git

Une fois Forgejo accessible, il est recommandé de vérifier qu’un dépôt peut être utilisé normalement.

Enfin, vérifier depuis l’interface Forgejo que le commit et les fichiers ont bien été enregistrés.

Résumé des vérifications

Après un déploiement, les éléments suivants doivent être validés :

• Le conteneur Forgejo est démarré.
• Les logs Forgejo ne contiennent pas d’erreur bloquante.
• Les volumes de données sont correctement montés.
• Caddy possède une configuration valide.
• Caddy fonctionne correctement.
• Forgejo est accessible depuis l’extérieur en HTTPS.
• La connexion à un compte fonctionne.
• Un dépôt Git peut être cloné.
• Un commit peut être poussé vers Forgejo.
• Les Forgejo Runners apparaissent comme actifs.
• Un workflow CI/CD peut être exécuté.

Points d’attention

Sauvegardes

Le déploiement de Forgejo ne constitue pas à lui seul une sauvegarde.

Les éléments importants à sauvegarder sont notamment :

• les dépôts Git ;
• la base de données si une base externe est utilisée ;
• la configuration Forgejo ;
• les données persistantes de Forgejo ;
• les éventuels fichiers ou secrets nécessaires à la restauration.

Une stratégie de sauvegarde doit permettre de restaurer Forgejo sur un nouveau serveur en cas de perte du VPS.

Mises à jour

Forgejo étant exécuté dans Docker, les mises à jour peuvent généralement être réalisées en mettant à jour l’image utilisée puis en recréant le conteneur.

Avant toute mise à jour importante, il est recommandé de :

1. vérifier les notes de version ;
2. effectuer une sauvegarde ;
3. vérifier que les données sont persistantes ;
4. mettre à jour l’image ;
5. redémarrer Forgejo ;
6. vérifier les logs ;
7. tester l’accès Web et les opérations Git ;
8. tester les Forgejo Runners.

---