====== Service benevalibre.chapril.org ======

===== Introduction =====

  * Ce service est basé sur Bénévalibre.
  * Site principal : https://benevalibre.chapril.org/
  * Sources : https://forge.cliss21.org/cliss21/benevalibre
  * Documentation : https://benevalibre.chapril.org/docs

===== Installation des pré-requis =====

<code bash>
apt install libapache2-mod-wsgi-py3 python3 virtualenv git make
</code>

Le serveur de base de donnée MariaDB imposé par cette version de Django nécessite pas mal de dépendances de développement%%*%%.

<code bash>
apt install build-essential python3-dev libmariadb-dev pkg-config
</code>

%%*%% Le connecteur de Debian n'étant pas assez récent.

===== Préparation de la DB =====

<code bash>
mysql -u root -p
</code>

<code sql>
CREATE DATABASE benevalibre ;
CREATE USER 'benevalibre' IDENTIFIED BY 'xxxxxxxxx';
GRANT ALL PRIVILEGES ON `benevalibre`.* To 'benevalibre' IDENTIFIED BY 'xxxxxxxxx';
</code>

===== Préparation des dossiers =====

<code bash>
mkdir /srv/benevalibre.chapril.org
cd /srv/benevalibre.chapril.org/
mkdir -p /var/log/benevalibre.chapril.org
mkdir -p /var/www/benevalibre.chapril.org
ln -s /var/www/benevalibre.chapril.org www
cd www/
</code>

===== Installation de Bénévalibre =====

<code bash>
git clone https://forge.cliss21.org/cliss21/benevalibre.git
cd benevalibre/
git checkout master
</code>

On doit installer le connecteur SQL donc on procède en deux temps.

<code bash>
make create-venv
venv/bin/pip install mysqlclient
make init
</code>

Durant le ''make init'' un éditeur s'ouvre pour qu'on fasse la configuration de l'application.
Je retiens ceci :

<file - config.env>
ENV=production
DJANGO_SECRET_KEY=s3cr3t
DJANGO_ALLOWED_HOSTS=benevalibre.chapril.org,
DJANGO_DATABASE_URL=mysql://benevalibre:xxxxxxxxxx@127.0.0.1:3306/benevalibre
DEFAULT_FROM_EMAIL=benevalibre@chapril.org
ADMINS=benevalibre-support@chapril.org
</file>

Le ''make init'' se charge de :

  *  Mettre à jour le ''virtualenv'' ;
  *  Vérifier le chargement du logiciel ;
  *  Appliquer les migrations de base ;
  *  Collecter les statiques ;
  *  Compiler la documentation.

===== Configuration Apache2 =====

On adapte la configuration de Nginx fournie par le fichier ''README.md'' en suivant la logique documentée pour un [[https://docs.djangoproject.com/fr/3.1/howto/deployment/wsgi/modwsgi/|projet Django]]:

<file apache /etc/apache2/sites-available/benevalibre.chapril.org.conf>
<VirtualHost *:80>
    ServerName benevalibre.chapril.org
    ServerAdmin benevalibre-support@chapril.org

    ErrorLog ${APACHE_LOG_DIR}/benevalibre.chapril.org/benevalibre.chapril.org-error.log
    CustomLog ${APACHE_LOG_DIR}/benevalibre.chapril.org/benevalibre.chapril.org-access.log combined-proxy

    WSGIProcessGroup benevalibre
    WSGIDaemonProcess benevalibre python-home=/var/www/benevalibre.chapril.org/benevalibre/venv/ python-path=/var/www/benevalibre.chapril.org/benevalibre/

    WSGIScriptAlias / /var/www/benevalibre.chapril.org/benevalibre/benevalibre/wsgi.py process-group=benevalibre

    <Directory /var/www/benevalibre.chapril.org/benevalibre/benevalibre/>
        <Files wsgi.py>
            Require all granted
        </Files>
    </Directory>

    Alias /static/ /var/www/benevalibre.chapril.org/benevalibre/var/static/

    <Directory /var/www/benevalibre.chapril.org/benevalibre/var/static/>
        Require all granted
    </Directory>

    Alias /media/ /var/www/benevalibre.chapril.org/benevalibre/var/media/

    <Directory /var/www/benevalibre.chapril.org/benevalibre/var/media/>
        Require all granted
    </Directory>

    Alias /favicon.ico /var/www/benevalibre.chapril.org/benevalibre/var/static/favicon/favicon.ico
</VirtualHost>
</file>

===== Configuration monitoring =====

<file nagios /etc/icinga2/zones.d/master/cluster/lamp.conf>
/* == benevalibre.chapril.org == */
vars.http_vhosts["benevalibre.chapril.org"] = {
  http_vhost = "benevalibre.chapril.org"
  http_uri = "/"
  vhost_tls = "redirect"
  http_string = "Le logiciel libre qui facilite la gestion et la valorisation du bénévolat dans les associations."
}
</file>

===== Tester l'envoi de courriels =====

<code bash>
cd /var/www/benevalibre.chapril.org/benevalibre
./venv/bin/python manage.py sendtestemail benevalibre-support@chapril.org
</code>

===== Personnaliser la présentation du logiciel =====

Fait via le dossier ''local/'' tel qu'indiqué dans le fichier ''README.md'' du projet.

===== Création d'un utilisateur admin =====

On se place en utilisateur ''www-data'' :

<code bash>
su - www-data -s /bin/bash
</code>

<code bash>
cd /var/www/benevalibre.chapril.org/benevalibre/

./venv/bin/python manage.py createsuperuser
</code>
<code>
Adresse mail: benevalibre-support@chapril.org
Password: 
Password (again): 
Superuser created successfully.
</code>

Puis :

  * Ajouter le mot de passe dans le gestionnaire dédié ;
  * Se connecter au service Web :
    * Mettre « ChaprilAdmin » en pseudonyme,
    * Mettre un avatar Chapril : {{:chapril-logo-compte.png?direct&50|Logotype du Chapril}}.

===== Administration régulière du service =====

==== Export/import de la base de données ====

<code bash>
mysqldump -u root -p benevalibre > benevalibre_backup_db_$(date +%Y%m%d).sql
</code>

<code bash>
mysql -u root -p benevalibre < benevalibre_backup_db_$(date +%Y%m%d).sql
</code>

==== Mise à jour de bénévalibre (version < 2.0.0) ====

<code bash>
git pull && make update
</code>

Une autre procédure est possible :

<code bash>
cd /var/www/benevalibre.chapril.org/benevalibre/
git fetch --all
git rebase origin/master
make update
chown www-data: . -R
</code>

===== Administration exceptionnelle du service =====

==== Mise à jour de Bénévalibre de la v1.6.x à la version 2.0.x ====

En août 2025, la sortie de la version 2.0 de Bénévalibre a été annoncée.
Comme indiquée dans l'annonce du forum ([[https://forum.benevalibre.org/d/367-sortie-de-la-v200|sortie de la version 2]]), cette mise à jour amène une ré-écriture d'une partie du code source.

La procédure d'installation //fraîche// a changé, ainsi que la procédure de mise à jour.

Le protocole qui suit, en cours d'écriture, est celui prévu pour mettre à jour l'instance du Chapril.

=== Arrêt ===

Commençons par arrêter le service.

<code bash>
a2dissite benevalibre.chapril.org
systemctl reload apache2
</code>

=== Sauvegarde ===

Sauvegardons ensuite notre configuration et les fichiers statiques, logos…

Si besoin, créer un dossier de sauvegarde.

<code bash>
mkdir ~/backup
</code>

On sauvegarde le nécessaire ailleurs.
<code bash>
cd /var/www/benevalibre.chapril.org/benevalibre/
cp -rp {config.env,var} ~/backup/
</code>

=== Mise à jour ===

On s'assure d'être sur la branche actuelle du code et on tire les dernières modifications.

<code bash>
git checkout main && git pull
</code>

Copie de notre fichier ''config.env'' original et du fichier d'exemple de la nouvelle version.
<code bash>
cp config.env config.env.ori
cp config.env.example config.env
</code>

On reporte les éléments de notre ancienne configuration dans le nouveau fichier, à savoir les variables :
<code - config.env>
DJANGO_SECRET_KEY=s3cr3t
DJANGO_ALLOWED_HOSTS=benevalibre.chapril.org,
DJANGO_DATABASE_URL=mysql://benevalibre:xxxxxxxxxx@127.0.0.1:3306/benevalibre
DEFAULT_FROM_EMAIL=benevalibre@chapril.org
ADMINS=benevalibre-support@chapril.org
</code>

<note important>
On éditera la variable ''BASE_URL'', sinon le service ne fonctionnera pas.
<code bash>
   BASE_URL=https://benevalibre.chapril.org
</code>
</note>

<note>
Les variables ''OPEN_REGISTRATION'' et ''MODERATED_REGISTRATION'' sont renommées respectivement en ''ASSOCIATION_REGISTRATION_OPEN'' et ''ASSOCIATION_REGISTRATION_MODERATED''.

Dans notre cas, nous conservons les valeurs par défaut.
</note>

=== Installation de l'environnement virtuel ===

Après avoir supprimé l'ancien répertoire ''venv/'', on installe Benevalibre, comme indiqué dans la documentation.

<code bash>
rm -rf ./venv
</code>

<code bash>
python3 -m venv --system-site-packages ./venv
source ./venv/bin/activate
python -m pip install benevalibre
</code>

''(venv)'' doit préfixer l'invité de commande.

On vérifie que tout va bien avec l'environnement virtuel activé, avant de poursuivre.

<code bash>
python -m benevalibre check --deploy
</code>

On passera sous silence, les erreurs affichées concernant les options ''SECURE_HSTS_SECONDS'' et ''SECURE_SSL_REDIRECT'' de Django.

Avant de poursuivre on réalisera la commande suivante :
<code bash>
ln -s /var/www/benevalibre.chapril.org/benevalibre/venv/lib/python3.11/site-packages/benevalibre/static \
/var/www/benevalibre.chapril.org/benevalibre/benevalibre/static
</code>

Ceci permettra de rattraper un bug lors de la collecte des fichiers statiques qui va suivre.

On migre la base de données et on récupère les fichiers statiques dans l'environnement virtuel.

<code bash>
python -m benevalibre migrate
python -m benevalibre collectstatic
</code>

<note important>
Avant de lancer la dernière commande, on s'assurera de la présence du répertoire ''./var/media/''.
</note>

=== Installation de Gunicorn ===

La mise à jour propose d'utiliser [[https://gunicorn.org/|Gunicorn]] pour servir l'application.
Trois tâches sont à faire.

Installer Gunicorn dans le répertoire ''venv/'' de Bénévalibre avant de désactiver l'environnement virtuel.

<code bash>
python -m pip install gunicorn
deactivate
</code>

Créer puis activer un service Systemd pour lancer Gunicorn qui va servir Bénévalibre.

<code ini /etc/systemd/system/benevalibre.service>
[Unit]
Description=Bénévalibre web service
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/benevalibre.chapril.org/benevalibre
ExecStart=/var/www/benevalibre.chapril.org/benevalibre/venv/bin/gunicorn benevalibre.wsgi \
    --name benevalibre --workers 4 \
    --max-requests 1200 --max-requests-jitter 50 \
    --log-level=info --bind=127.0.0.1:8345
Restart=on-failure

[Install]
WantedBy=multi-user.target
</code>

<code bash>
systemctl daemon-reload
systemctl enable --now benevalibre
</code>

Modifier la configuration d'Apache afin de rediriger les requêtes vers Gunicorn.

<code apache /etc/apache2/sites-available/benevalibre.chapril.org [enable_line_numbers="true",highlight_lines_extra="22,23,24,25,26,27,28,29"]>
<VirtualHost *:80>
    ServerName benevalibre.chapril.org
    ServerAdmin benevalibre-support@chapril.org

    ErrorLog ${APACHE_LOG_DIR}/benevalibre.chapril.org/benevalibre.chapril.org-error.log
    CustomLog ${APACHE_LOG_DIR}/benevalibre.chapril.org/benevalibre.chapril.org-access.log combined-proxy

    Alias /static /var/www/benevalibre.chapril.org/benevalibre/var/static

    <Directory /var/www/benevalibre.chapril.org/benevalibre/var/static/>
        Require all granted
    </Directory>

    Alias /media /var/www/benevalibre.chapril.org/benevalibre/var/media

    <Directory /var/www/benevalibre.chapril.org/benevalibre/var/media>
        Require all granted
    </Directory>

    Alias /favicon.ico /var/www/benevalibre.chapril.org/benevalibre/var/static/favicon/favicon.ico

    ProxyRequests Off
    ProxyPreserveHost On

    ProxyPass /static !
    ProxyPass /media !
    ProxyPass /favicon.ico !
    ProxyPass / http://localhost:8345/
    ProxyPassReverse / http://localhost:8345/
    
    # ChaprilInfos
    Include chaprilinfos.conf

</VirtualHost>
</code>

On ajoutera le module ''proxy'' avant de réactiver la configuration de Bénévalibre et de relancer Apache.

<code bash>
a2enmod proxy
a2enmod proxy_http
a2ensite benevalibre.chapril.org
systemctl restart apache2
</code>