forge/README.md

# Service forge.chalec.org

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

Responsable: Christian Momon (@cpm)

Anciens responsables : n/a.

La première version de cette documentation est basée sur la [documentation Devinsy](urlhttps://forge.devinsy.fr/adminsys/documentation/src/branch/master/forge.devinsy.fr.md).

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

À noter l'absence de paquet dans Debian : https://docs.gitea.io/en-us/install-from-package/#debian

À noter l'absence de paquet deb pertinent :

>     Although there is a package of Gitea in Debian’s contrib, it is not supported directly by us.
>     Unfortunately, the package is not maintained anymore and broken because of missing sources.
>     Please follow the deployment from binary guide instead.

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/.


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

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

```
su -c "psql" - postgres
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/gitea/ \
   git
```

## Préparation des fichiers

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

```
export GITEA_WORK_DIR=/srv/gitea
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/git
chown root:gitea /etc/gitea
chmod ug+rwx /etc/gitea
chmod o-rwx /etc/gitea
```

Création du dossier de logs (optionnel) :
```
mkdir /var/log/gitea
chown git.git /var/log/gitea
```

## 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 :
```
cd /srv/gitea/bin/
wget -O gitea https://dl.gitea.io/gitea/$GITEA_VERSION/gitea-$GITEA_VERSION-linux-amd64
chown root:git . gitea
chmod g=rx . gitea
```

Installer gpg :
```
apt-get install gpg
```

Vérifier sa signature :
```
wget https://dl.gitea.io/gitea/$GITEA_VERSION/gitea-$GITEA_VERSION-linux-amd64.asc
gpg --keyserver pgp.mit.edu --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
gpg --verify gitea-$GITEA_VERSION-linux-amd64.asc gitea
```


## Intégration du service dans Systemd

La documentation de Gitea contient une page dédiée :

    https://docs.gitea.io/en-us/linux-service/

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

    https://github.com/go-gitea/gitea/blob/master/contrib/systemd/gitea.service

Fichier personnalisé pour la forge Chalec à mettre dans /etc/systemd/system/gitea.service :
```
[Unit]
Description=Gitea (Git with a cup of tea)
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/gitea/
ExecStart=/srv/gitea/bin/gitea web --config /etc/gitea/gitea.ini
Restart=always
Environment=USER=git HOME=/srv/gitea/ GITEA_WORK_DIR=/srv/gitea

[Install]
WantedBy=multi-user.target
```

Démarrage et activation du service :
```
systemctl enable gitea.service
systemctl start gitea.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 : giteadba
  - mot de passe : xxxxxxxxxxxx
  - nom de la base : giteadb
  - SSL : Disable
  - Schéma : vide
- configuration générale :
  - titre du site : La forge Chalec
  - exécuter avec le compte d'un autre utilisateur : git
  - domaine du serveur SSH : forge.chalec.org
  - chemin des fichiers log : /var/log/gitea/
  - laisser les autres valeurs par défaut
- paramètres facultatifs :
  - paramètres emails :
  - hôte SMTP : localhost:25
  - envoyer les mails en tant que : ne-pas-repondre@forge.chalec.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 : oui
  - activer le suivi de temps par défaut : NON
  - paramètres de compte administrateur :
  - nom :  chalecadmin (admin est refusé par le formulaire)
  - mot de passe : xxxxxxxxxxx
  - adresse email : admin@chalec.org

Puis cliquer sur « Installer Gitea ».


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

Précautions :
```
chown -R root:git /etc/gitea
chmod g=rx /etc/gitea
chmod g=r /etc/gitea/gitea.ini
```

Vérifier que :
```
[server]
ROOT_URL         = https://forge.chalec.org/
```

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

## Courriels

Gitea a besoin de pouvoir envoyer des courriels, pour la gestion des comptes et pour les notifications.

Configuration la section dédiée dans `/srv/gitea/gitea.ini` :
```
[mailer]
ENABLED       = true
FROM          = no-reply@forge.chalec.org
PROTOCOL      = sendmail
SENDMAIL_PATH = /usr/sbin/sendmail
```

Pour Postfix, modifier `/etc/postfix/transport` :
```
 a-lec.org    :
 chalec.org   :
-*              discard:
```

Et activer :
```
postmap /etc/postfix/transport
```



## 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/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/gitea/custom/public/img
cd /srv/gitea/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/gitea/custom/public/img
cd /srv/gitea/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/gitea/custom/templates/
cd /srv/gitea/custom/public/templates/
wget https://raw.githubusercontent.com/go-gitea/gitea/release/v1.16/templates/home.tmpl
mv home.tmpl home.tpml.ori
wget https://git.a-lec.org/a-lec/commissions/chalec/forge/-/raw/main/custom/templates/home.tmpl
systemctl restart gitea
```

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.

# Mettre à jour

Constat :

* Gitea 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.

## Méthode automatique
Voir le script `update-gitea`.

## Méthode manuelle

Les étapes de la méthode manuelle :
* définir dans une variable le numéro de la nouvelle version :
```
export VERSION=1.X.Y
```

* récupérer la dernière version sur https://dl.gitea.io/gitea et faire un sha256sum -c :
```
cd /srv/gitea/bin
wget https://dl.gitea.io/gitea/$VERSION/gitea-$VERSION-linux-amd64
wget https://dl.gitea.io/gitea/$VERSION/gitea-$VERSION-linux-amd64.asc
wget https://dl.gitea.io/gitea/$VERSION/gitea-$VERSION-linux-amd64.sha256
sha256sum -c gitea-$VERSION-linux-amd64.sha256
# gpg --keyserver keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
gpg --verify gitea-$VERSION-linux-amd64.asc gitea-$VERSION-linux-amd64
```

* flusher :
```
cd /srv/gitea/bin
./gitea -c /etc/gitea/gitea.ini manager flush-queues
```

* stopper :
```
systemctl stop gitea
```

* dumper :
```
su - gitea -c "cd /srv/gitea/bin ; /srv/gitea/bin/gitea dump --tempdir /var/tmp/ -c /etc/gitea/gitea.ini"
```

* appeler le docteur :
```
cd /srv/gitea/bin
./gitea doctor --all --fix -c /etc/gitea/gitea.ini
```

* mettre les bons droits :
```
cd /srv/gitea/bin/
chown git.gitea gitea-$VERSION-linux-amd64
chmod u+x gitea
```

* remplacer le binaire /srv/gitea/bin/gitea :
```
ln --force gitea-$VERSION-linux-amd64 gitea
```

* démarrer :
```
systemctl start gitea
```

* surveiller les logs :
```
journal -f
```
ou suivant la configuration :
```
tail -f /var/log/gitea/gitea.log
```

* supprimer manuellement l'ancien dump et les anciennes versions.