Service forge.chalec.org

Service de forge logicielle du chaton de Libre en communs basé sur le logiciel libre Gitea : https://gitea.io/.

Responsable: Adrien Bourmault (@neox)

Anciens responsables : Christian Momon (@cpm).

La première version de cette documentation est basée sur la documentation Devinsy.

Procédure d'installation inspirée de https://docs.gitea.io/en-us/install-from-binary/ où Gitea consiste en un unique binaire.

Né en décembre 2022, Forgejo est un projet très jeune qui se réferre encore beaucoup à Gitea, la source de son fork. Notamment pour sa documentation.

Note : la documentation est traduite en français mais pas complétement. La consultation en version française peut vous faire perdre beaucoup d'informations utiles. Voir par exemple entre https://docs.gitea.io/en-us/install-from-binary/ et https://docs.gitea.io/fr-fr/install-from-binary/.

Note : pour l'instant, Forgejo est un soft fork de Gitea, avec la volonté d'être interchangeable. Cela a pour conséquence que certaines variables d'envrionnement et certains messages contiennent le nom Gitea au lieu du nom Forgejo.

Intallation

Prérequis système

Vérifier que le fichier /etc/hosts.deny ne bloque pas les connexions ssh :

#sshd: ALL

NGinx

Installer les paquets :

apt-get install nginx python3-certbot-nginx

Ouvrir les ports http (80) et https (443) :

ufw allow 'Nginx HTTP'
ufw allow 'Nginx HTTPS'

Configurer a minima le site web dans /etc/nginx/sites-available/forge.chalec.org :

server
{
    listen 80;
    listen [::]:80;

    server_name forge.chalec.org; 

    access_log /var/log/nginx/forge.chalec.org-access.log;
    error_log /var/log/nginx/forge.chalec.org-error.log;
}

Activer la configuration :

cd /etc/nginx/sites-enabled/
ln -s ../sites-available/forge.chalec.org

Vérifier que c'est bon et recharger :

nginx -t && systemctl reload nginx

Configurer le certificat SSl :

certbot --nginx 

Créer un fichier générique cat /etc/nginx/statoolinfos.conf qui sera includé plus tard :

   location /.well-known/statoolinfos/ 
   {
       types 
       {
            text/plain    properties;
       }

       alias /srv/statoolinfos/well-known/statoolinfos/;
       autoindex on;
   }

Mettre beau le fichier /etc/nginx/sites-enabled/forge.chalec.org :

server
{
    listen 80;
    listen [::]:80;

    server_name forge.chalec.org;

    access_log /var/log/nginx/forge.chalec.org-access.log;
    error_log /var/log/nginx/forge.chalec.org-error.log;

    #return 302 https://$host$request_uri;
    return 302 https://forge.chalec.org$request_uri;
}

server
{
    set_real_ip_from  192.169.1.1;
    real_ip_header proxy_protocol;
    listen [::]:443 ssl ipv6only=on;
    listen 443 ssl proxy_protocol;

    server_name forge.chalec.org;

    access_log /var/log/nginx/forge.chalec.org-access.log;
    error_log /var/log/nginx/forge.chalec.org-error.log;

    ssl_certificate /etc/letsencrypt/live/forge.chalec.org/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/forge.chalec.org/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

    # StatoolInfos.
    include /etc/nginx/statoolinfos.conf;

    location /
    {
        proxy_pass http://localhost:3000;
    }    
}

Vérifier que c'est bon et recharger :

nginx -t && systemctl reload nginx

Postgresql

apt install postgresql postgresql-contrib

D'après la documentation d'installation de Gitea :

PostgreSQL uses md5 challenge-response encryption scheme for password authentication by default. Nowadays this scheme is not considered secure anymore. Use SCRAM-SHA-256 scheme instead by editing the postgresql.conf configuration file on the database server to:

password_encryption = scram-sha-256

Restart PostgreSQL to apply the setting.

Le conseil semble judicieux donc éditer le fichier /etc/postgresql/13/main/postgresql.conf :

#password_encryption = md5              # md5 or scram-sha-256
password_encryption = scram-sha-256

Et redémarrer le service :

systemctl restart postgresql.service

Préparation de la base de données

Note : Gitea semble insister pour mettre un mot de passe pour l'accès à la base de données.

Se connecter à Postgresql :

su -c "psql" - postgres

Créer un utilisateur (« role » en langage Pgsql) :

CREATE ROLE giteadba WITH LOGIN PASSWORD 'xxxxxxxxxxxxx';

Créer une base de données :

CREATE DATABASE giteadb WITH OWNER giteadba TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'fr_FR.UTF-8' LC_CTYPE 'fr_FR.UTF-8';

Donner l'accès en éditant le ficher /etc/postgresql/13/main/pg_hba.conf :

local    giteadb    giteadba    scram-sha-256

Redémarrer le service :

systemctl restart postgresql.service

Création d'un utilisateur système dédié

Créer un utilisateur système dédié :

adduser \
   --system \
   --shell /bin/bash \
   --gecos 'Git Version Control' \
   --group \
   --disabled-password \
   --home /srv/forgejo/ \
   git

Préparation des fichiers

Création de l'arborescence dédiée :

export GITEA_WORK_DIR=/srv/forgejo
mkdir -p $GITEA_WORK_DIR/{bin,custom,data,tmp}
chown -R git:git $GITEA_WORK_DIR
chmod -R ug+x $GITEA_WORK_DIR
chmod -R o-rwx $GITEA_WORK_DIR

Création du dossier de configuration :

mkdir /etc/forgejo
chown root:git /etc/forgejo
chmod ug+rwx /etc/forgejo
chmod o-rwx /etc/forgejo

Création du dossier de logs (optionnel) :

mkdir /var/log/forgejo
chown git.git /var/log/forgejo

Récupération du binaire

Gitea consiste en un seul fichier binaire. Identifier la dernière version : https://dl.gitea.io/gitea/

Définir la version cible :

export GITEA_VERSION=1.XX.X

La télécharger :

mkdir -p /srv/forgejo/bin/
cd /srv/forgejo/bin/
wget https://codeberg.org/forgejo/forgejo/releases/download/v${VERSION}/forgejo-${VERSION}-linux-amd64

Vérifier cohérence du fichier :

wget https://codeberg.org/forgejo/forgejo/releases/download/v${VERSION}/forgejo-${VERSION}-linux-amd64.sha256
sha256sum -c forgejo-${VERSION}-linux-amd64.sha256

Installer gpg :

apt-get install gpg

Vérifier sa signature :

wget https://codeberg.org/forgejo/forgejo/releases/download/v${VERSION}/forgejo-${VERSION}-linux-amd64.asc
gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
gpg --verify forgejo-${VERSION}-linux-amd64.asc forgejo-${VERSION}-linux-amd64

Renommer :

ln -s forgejo-${VERSION}-linux-amd64 forgejo
chown root:git . forgejo
chmod g=rx . forgejo

Intégration du service dans Systemd

Forgejo propose un fichier prêt à l'emploi dont il faut modifier manuellement quelques paramètres.

Fichier personnalisé à mettre dans /etc/systemd/system/forgejo.service :

[Unit]
Description=Forgejo (Beyond coding. We forge.)
After=syslog.target
After=network.target
Wants=postgresql.service
After=postgresql.service

[Service]
# Modify these two values and uncomment them if you have
# repos with lots of files and get an HTTP error 500 because
# of that
###
#LimitMEMLOCK=infinity
#LimitNOFILE=65535
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/srv/forgejo/
ExecStart=/srv/forgejo/bin/forgejo web --config /etc/forgejo/forgejo.ini
Restart=always
Environment=USER=git HOME=/srv/forgejo/ GITEA_WORK_DIR=/srv/forgejo

[Install]
WantedBy=multi-user.target

Démarrage et activation du service :

systemctl daemon-reload
systemctl enable forgejo.service
systemctl start forgejo.service

Premier démarrage

Suite au premier démarrage, ouvrir un navigateur web sur le site et cliquer sur « connexion ». Alors une page de configuration générale s'ouvre. La remplir comme suit :

• base de données :
• type de base de données : Postgresql
• hôte : 127.0.0.1:5432
• nom d'utilisateur : forgejodba
• mot de passe : xxxxxxxxxxxx
• nom de la base : forgejodb
• SSL : Disable
• Schéma : vide
• configuration générale :
• titre du site : La forge Libre en Communs
• Emplacement racine des dépôts : /srv/forgejo/data/forgejo-repositories
• Répertoire racine Git LFS : /srv/forgejo/data/lfs
• exécuter avec le compte d'un autre utilisateur : git
• domaine du serveur : forge.a-lec.org
• chemin des fichiers log : /var/log/forgejo/
• laisser les autres valeurs par défaut
• paramètres facultatifs :
• paramètres emails :
• hôte SMTP : localhost
• port SMTP : 25
• envoyer les mails en tant que : ne-pas-repondre@forge.a-lec.org
• exiger la confirmation de l'email lors de l'inscription : oui
• activer les notifications par email : oui
• paramètres serveurs et tierces parties :
• activer le mode hors-ligne : OUI (servira toutes les ressources localement)
• désactiver Gravatar : OUI
• activer les avatars unifiés : NON
• activer l'inscription OpenID : NON
• désactiver le formulaire d'inscription : non
• n'autoriser l'inscription qu'à partir des services externes : non
• activer l'inscription OpenID : non
• activer le CAPTCHA : OUI
• exiger la connexion à un compte pour afficher les pages : non
• masquer les adresses e-mail par défaut : non
• autoriser la création d'organisation par défaut : NON
• activer le suivi de temps par défaut : NON
• Domaine pour les e-mails cachés : noreply.localhost
• paramètres de compte administrateur :
• nom : alecadmin (admin est refusé par le formulaire)
• mot de passe : xxxxxxxxxxx
• adresse email : admin@a-lec.org

Puis cliquer sur « Installer Forgejo ».

Un fichier de configuration a été créé dans /etc/forgejo/forgejo.ini. Par la suite, les valeurs pourront être modifiées dans ce fichier.

Précautions :

chown -R root:git /etc/forgejo
chmod g=rx /etc/forgejo
chmod g=r /etc/forgejo/forgejo.ini

Vérifier que :

[server]
ROOT_URL         = https://forge.a-lec.org/

Pour vérifier, lancer un test via Gitea > Site Administration > Configuration > SMTP Mailer Configuration > Envoyer un e-mail de test.

Licences préférées

Extrait de la documentation :

PREFERRED_LICENSES: Apache License 2.0,MIT License:
Preferred Licenses to place at the top of the list.
Name must match file name in conf/license or custom/conf/license.

Les noms de fichiers à utiliser sont présents dans les sources : https://github.com/go-gitea/gitea/tree/master/options/license

Paramétrage dans /etc/gitea/gitea.ini :

[repository]
PREFERRED_LICENSES=AGPL-3.0-or-later,GPL-3.0-or-later,CC-BY-SA-4.0

Taille maximale de téléversement

Par défaut, la taille maximale d'un téléversement est limité à 3 Mo. Pour augmenter la taille (à 20 Mo pour la forge Chalec), ajouter une section dans /etc/forgejo/forgejo.ini :

[repository.upload]
; Whether repository file uploads are enabled. Defaults to `true`
; ENABLED = true
; Path for uploads. Defaults to `data/tmp/uploads` (tmp gets deleted on gitea restart)
; TEMP_PATH = data/tmp/uploads
; One or more allowed types, e.g. image/jpeg|image/png. Nothing means any file type
; ALLOWED_TYPES =
; Max size of each file in megabytes. Defaults to 3MB
FILE_MAX_SIZE = 20
; Max number of files per upload. Defaults to 5
; MAX_FILES = 5

Pour les téléversements de version (release) :

[attachment]
; Max size of each file. Defaults to 4MB
MAX_SIZE = 20

Taille maximale de téléversement

Par défaut, la taille maximale d'un téléversement est limité à 3 Mo. Pour augmenter la taille (à 20 Mo pour la forge Chalec), ajouter une section dans /etc/gitea/gitea.ini :

[repository.upload]
; Whether repository file uploads are enabled. Defaults to `true`
; ENABLED = true
; Path for uploads. Defaults to `data/tmp/uploads` (tmp gets deleted on gitea restart)
; TEMP_PATH = data/tmp/uploads
; One or more allowed types, e.g. image/jpeg|image/png. Nothing means any file type
; ALLOWED_TYPES =
; Max size of each file in megabytes. Defaults to 3MB
FILE_MAX_SIZE = 20
; Max number of files per upload. Defaults to 5
; MAX_FILES = 5

Pour les téléversements de version (release) :

[attachment]
; Max size of each file. Defaults to 4MB
MAX_SIZE = 20

Personnalisation

Favicon + logo barre

Enrichir l'arborescence de personnalisation :

mkdir -p /srv/forgejo/custom/public/img
cd /srv/forgejo/custom/public/img
wget https://git.a-lec.org/a-lec/commissions/chalec/forge/-/raw/main/forge.chalec.org-logo.svg
mv forge.chalec.org-logo.svg logo.svg
cp logo.svg favicon.svg
chmod go+r *

Page d'accueil

Ajouter le logo sans marge (pour gagner de la place d'affichage) :

mkdir -p /srv/forgejo/custom/public/img
cd /srv/forgejo/custom/public/img
wget https://git.a-lec.org/a-lec/commissions/chalec/forge/-/raw/main/forge.chalec.org-logo-nomarge.svg
chmod go+r *

Télécharger le code de la page d'accueil officielle et la remplacer par une version personnalisée :

mkdir -p /srv/forgejo/custom/templates/
cd /srv/forgejo/custom/public/templates/
wget https://raw.githubusercontent.com/go-gitea/gitea/release/v1.16/templates/home.tmpl
mv home.tmpl home.tpml.bak
wget https://git.a-lec.org/a-lec/commissions/chalec/forge/-/raw/main/custom/templates/home.tmpl
systemctl restart forgejo

La version personnalisée du code la page d'accueil est là : https://git.a-lec.org/a-lec/commissions/chalec/forge/-/raw/main/home.tmpl. Ce code est potentiellement impacté par les mises à jour et sera à vérifier à chaque fois.

Mise à jour

Constat :

• Forgejo consiste en un seul fichier binaire, une base de données, une arborescence de fichiers ;
• la documentation officielle de Gitea contient une page sur les backups : https://docs.gitea.io/en-us/backup-and-restore/.

Donc la procédure de mise à jour consiste juste à faire un export puis relancer avec le nouveau binaire.

ATTENTION : toujours lire changelog avant toute mise à jour /!/!/!\

Installer les scripts :

cd /srv/forgejo/bin/
wget https://git.a-lec.org/a-lec/commissions/infrastructure/forge/-/raw/main/bin/check_update
wget https://git.a-lec.org/a-lec/commissions/infrastructure/forge/-/raw/main/bin/upgrade
wget https://git.a-lec.org/a-lec/commissions/infrastructure/forge/-/raw/main/bin/doctor
chmod u+x check_update upgrade doctor

Vérifier la disponibilité d'une mise à jour :

cd /srv/forgejo/bin/
./check_update

Mise à jour automatique via le script bin/upgrade :

cd /srv/forgejo/bin/
./upgrade 1.XX.YY-ZZ

Démarrer :

systemctl start forgejo ; systemctl status forgejo ; journal -f -u forgejo

Ou suivant la configuration :

systemctl start forgejo ; systemctl status forgejo ; tail -f /var/log/forgejo/forgejo.log

Faire manuellement le nettoyage dans les anciens dump et les anciennes versions.

StatoolInfos

Le déploiement de StatoolInfos se fait selon la procédure nominale.

Quelques remarques :

• forcer IPv6 dans le script statoolinfos ;
• créer un token admin pour la génération de métriques spécifiques.