Guide d’installation

Ce guide vous aidera à installer Bénévalibre sur un serveur sous GNU/Linux. Pour la mise à jour, veuillez vous référer à la procédure donnée dans l’annonce du forum pour cette version.

Pré-requis

• Python 3.10 ou plus récent
• Une base de données, de préférence PostgreSQL
• Un reverse proxy comme NGINX pour servir l’application en HTTPS ainsi que ses fichiers
• Un accès à un serveur SMTP pour l’envoi de mail (inscription d’un compte, notifications…)

Sur un serveur sous Debian, il est recommandé d’installer les paquets suivant :

• python3
• python3-venv
• python3-pil
• python3-psycopg2 (pour une base de données PostgreSQL)

Étape 1 : Utilisateur UNIX

Comme nous ne souhaitons pas utiliser le compte root pour faire tourner l’application, nous commençons par créer un utilisateur non-privilégié :

# adduser benevalibre --disabled-password --home /home/benevalibre

Pour information, toutes les commandes de ce guide commençant par # sont à exécuter en tant que l’utilisateur root. À l’inverse, celles qui commencent par $ sont à exécuter avec ce nouvel utilisateur – benevalibre dans notre cas. Enfin, (venv)$ indique que l’environnement virtuel qui sera créé plus bas doit être activé.

Étape 2 : Base de données

Il est au moins possible d’utiliser une base de données PostgreSQL ou SQLite.

Pour de bonnes performances en production, nous recommandons vivement d’utiliser PostgreSQL. Dans ce cas, il vous faudra créer au préalable une base de données ainsi qu’un utilisateur ayant toutes les permissions sur celle-ci. Par exemple :

# sudo -u postgres createuser benevalibre -P
# sudo -u postgres createdb -O benevalibre benevalibre

Étape 3 : Configuration

La configuration de votre instance peut se faire soit depuis un fichier de configuration, soit depuis les variables d’environnement. Dans les deux cas, les variables disponibles sont documentées dans le fichier config.env.example. Dans le cas d’un fichier de configuration, son chemin peut être défini par la variable d’environnement CONFIG_FILE. Si elle n’est pas définie, l’application cherchera alors un fichier config.env dans le dossier courrant.

Dans ce guide, nous allons récupérer le fichier d’exemple et le stocker dans le dossier personnel du compte benevalibre :

$ curl --output ~/config.env https://forge.cliss21.org/cliss21/benevalibre/raw/branch/main/config.env.example
$ chmod 0600 benevalibre: benevalibre ~/config.env

Éditez ensuite le fichier ~/config.env avec votre éditeur favori pour ajuster la configuration de votre instance.

Étape 4 : Installation

Nous allons maintenant installer l’application ainsi que ses dépendances, grâce au paquet benevalibre disponible sur PyPI.

Cette installation se fera dans un environnement virtuel que nous allons créer au préalable dans le dossier personnel de l’utilisateur bénévalibre :

$ python3 -m venv --system-site-packages ~/venv

Ce nouvel environnement peut désormais être activé afin d’y installer Bénévalibre :

$ source ~/venv/bin/activate
(venv)$ python -m pip install benevalibre

Vous pouvez désormais vérifier que votre installation est prête pour le déploiement :

(venv)$ python -m benevalibre check --deploy

Si tout s’est bien passé, vous pouvez alors initialiser la base de données et collecter les fichiers statiques :

(venv)$ python -m benevalibre migrate
(venv)$ python -m benevalibre collectstatic

Vous pouvez aussi créer un compte administrateur de l’instance :

(venv)$ python -m benevalibre createsuperuser

Étape 5 : Lancement de l’application

Comme service avec Gunicorn

Il vous faudra installer le serveur Gunicorn soit dans l’environnement virtuel créé précédemment, soit depuis les paquets de votre distribution – gunicorn par exemple sous Debian.

Dans le cas d’un système utilisant systemd, le fichier /etc/systemd/system/benevalibre.service peut être créé avec le contenu suivant – adaptez si besoin le chemin vers l’exécutable gunicorn :

[Unit]
Description=Bénévalibre web service
After=network.target

[Service]
User=benevalibre
Group=benevalibre
WorkingDirectory=/home/benevalibre
ExecStart=/usr/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

Vous pouvez désormais activer et lancer le service :

# systemctl daemon-reload
# systemctl enable benevalibre
# systemctl start benevalibre

Étape 6 : Reverse proxy

Il nous reste à mettre en place un reverse proxy HTTP pour gérer les connexions HTTPS vers l’application. Vous pouvez utiliser celui de votre choix tant qu’il est suffisamment sécurisé et performant.

Voici un exemple de configuration dans le cas de NGINX, au sein d’un bloc server déjà existant :

location / {
  include uwsgi_params ;
  uwsgi_pass http://127.0.0.1:8345;
}
location /media {
  alias /home/benevalibre/var/media;
}
location /static {
  alias /home/benevalibre/var/static;
  # Optional: don't log access to assets
  access_log off;
}
location = /favicon.ico {
  alias /home/benevalibre/var/static/favicon.ico;
  # Optional: don't log access to the favicon
  access_log off;
}