====== Weblate ======

[[https://weblate.org/fr/|Weblate]] est une plateforme de traduction. Khaganat dispose de sa propre instance accessible depuis l'adresse [[https://locale.khaganat.net/]].

===== Installation =====

<WRAP center round important>Bien qu'il existe une documentation d'installation sur le site de Weblate et que ce guide y fait référence, vous êtes invité à ne pas la suivre aveuglément. En effet, certains choix technologiques sont différents (exemple : virtualenv vs. pipenv).</WRAP>

==== Architecture générale ====

Weblate utilise le framework Django et PostgreSQL comme base de données. Il existe plusieurs manières de déployer une application Django, ici nous utiliserons nginx et uWsgi. Nginx est le serveur web de base, c'est lui qui accepte les requêtes HTTP. Son rôle est, d'un côté, de servir les fichiers statiques présents dans un dossier (images, CSS, etc) et, de l'autre, de faire appel à uWsgi pour l'application en elle-même. Tout comme nginx, uWsgi est un démon qu'il convient de lancer. Son rôle est d'exécuter des applications web présentant une interface standard, comme par exemple Django. Bien que uWsgi soit capable de gérer lui-même des requêtes HTTP, nous n'utiliserons pas cette option car elle n'est pas suffisante : en effet, uWsgi n'est pas capable d'aller chercher les ressources statiques et notre application web n'aurait donc ni image ni feuilles de styles.

<code>
nginx
├── ressources statiques
└── uWsgi
    └── Django
        └── PostgreSQL
</code>

<WRAP center round info>Afin de ne pas entrer en collision avec les autres services, il convient de faire écouter nginx sur un port qui sera dédié à Weblate. Ce port non-standard sera invisible des utilisatrices finales car les requêtes passent d'abord par le reverse-proxy. Dans cette documentation, nous avons choisi le port 8000.</WRAP>

Cette page n'a pas vocation à traiter de la mise en place d'un serveur PostgreSQL ni de la gestion des bases de données, utilisatrices et permissions sur ce serveur.

==== Dépendences ====

Tout d'abord, assurons-nous que les paquets ''python3'' et ''pipenv'' sont bien installés.

Ensuite, la liste des dépendances spécifiques à Weblate est disponible dans [[https://docs.weblate.org/en/latest/admin/install/venv-debian.html|sa documentation]]. Notez qu'à cela il faut ajouter le paquet ''libacl1-dev''.

Enfin, pour notre déploiement, nous installons les paquets ''nginx-full'', ''uwsgi'' et ''uwsgi-plugin-python3''. Vérifions également que nous disposons d'un serveur PostgreSQL accessible avec un utilisateur et et une base de données dédiée. Assurons-nous également que le reverse-proxy redirige correctement les requêtes HTTP sur l'adresse et le port prévus.

==== Weblate ====

Afin d'installer Weblate en elle-même, il nous faut commencer par choisir un dossier dans lequel réaliser l'installation. Sur Jukni3, c'est ''/home/khaganat/weblate''.

<WRAP center round important>Dans cette section, toutes les commandes sont supposées être lancées depuis ce dossier.</WRAP>

Installons Weblate ainsi que la bibliothèque permettant d'utiliser PostgreSQL :

<code>pipenv --three install Weblate psycopg2-binary</code>

<WRAP center round tip>L'option ''<nowiki>--three</nowiki>'' n'est à préciser que si l'environnement virtuel n'a pas encore été créé.</WRAP>

Cette commande créé deux fichiers, ''Pipfile'' et ''Pipfile.lock''. Notez que la version de python est inscrite dans Pipfile et qu'il est possible de l'enlever afin de simplifier les mises à jour futures de Python.

<WRAP center round alert>Sur Jukni3, pour une raison inconnue, pipenv utilise les ''Pipfile'' et ''Pipfile.lock'' situés dans ''/home/khaganat'' au lieux de ''/home/khaganat/weblate''. Ça ne change pas grand chose sur le fond mais ça vaut le coup d'être précisé afin de ne pas être surpris en lisant ce guide.</WRAP>


En plus de ces deux fichiers, pipenv a créé un environnement virtuel dans un dossier spécifique. Bien entendu , nous aurons besoin de ce chemin pour configurer nginx, uWsgi et Weblate. Or, ce chemin est susceptible de changer lors de la mise à jour de Python et, de plus, doit pouvoir être détruit et reconstruit de zéro. Afin de ne pas avoir besoin de modifier sans cesse la configuration, nous allons créer deux liens symboliques qui pointeront vers ce dossier. Ainsi, si nous détruisons cet environnement virtuel, nous aurons simplement besoin de mettre à jour ces liens.

<code>ln -s "$(pipenv --venv)" weblate-venv
ln -s "$(pipenv --venv)/lib/$(pipenv run python -c 'import sys; print(f"python{sys.version_info.major}.{sys.version_info.minor}")')/site-packages/weblate" weblate-src
</code>

Nous avons donc maintenant ''weblate-venv'' et ''weblate-srv'' qui pointent respectivement vers la racine de l'environnement virtuel et l’installation de Weblate dans cet environnement virtuel. Si cet environnement virtuel venait à changer, il faudrait alors supprimer cet deux liens symboliques et les recréer.

Configurons maintenant Weblate. Pour ce faire, il faut créer un fichier dans l'environnement virtuel. Comme nous avons vu que les environnements virtuels sont jetables, nous n'allons pas le créer directement dedans mais dans notre dossier de travail et utiliser à nouveau l'astuce des liens symboliques, mais dans l'autre sens.

<code>cp weblate-src/settings_example.py settings.py
ln -s "$(pwd)/settings.py" weblate-src/settings.py</code>

Nous avons donc maintenant le fichier ''settings.py'' servant à configurer Weblate. Dans l'environnement virtuel, un lien symbolique pointe dessus. Nous pouvons désormais configurer Weblate en modifiant les options à notre guise, en particulier les suivantes :

  * [[https://docs.djangoproject.com/fr/3.0/ref/settings/#debug|DEBUG]] doit etre mis à ''False''
  * [[https://docs.djangoproject.com/fr/3.0/ref/settings/#std:setting-SECRET_KEY|SECRET_KEY]] doit etre mis à une valeur génée par la commande ''pipenv run python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())' ''
  * [[https://docs.djangoproject.com/fr/3.0/ref/settings/#allowed-hosts|ALLOWED_HOSTS]] doit etre mis à ''["locale.khaganat.net"]''
  * Dans [[https://docs.djangoproject.com/fr/3.0/ref/settings/#databases|DATABASES]] il faut indiquer l'adresse du serveur PostgreSQL, le nom de la base de données, le nom d'utilisateur et le mot de passe associé.
  * La liste [[https://docs.djangoproject.com/fr/3.0/ref/settings/#admins|ADMINS]] doit contenir ''("Khaganat", "contact@khaganat.net"),'' (ce n'est pas un compte utilisateur !)
  * ''DATA_DIR'' doit etre mis à ''"/home/khaganat/weblate/data"''
  * [[https://docs.djangoproject.com/fr/3.0/ref/settings/#default-from-email|DEFAULT_FROM_EMAIL]] et [[https://docs.djangoproject.com/fr/3.0/ref/settings/#server-email|SERVER_EMAIL]] doit etre mis à ''weblate@khaganat.net'' ou similaire
  * Toujours pour les emails, il peut être utile de spécifier [[https://docs.djangoproject.com/fr/3.0/ref/settings/#email-host|EMAIL_HOST]] et les variables qui suivent.

Pour connaître l'ensemble des directives de configuration qu'il est possible de définir, rendez-vous dans [[https://docs.djangoproject.com/fr/3.0/ref/settings/|la documentation de Django]] ainsi que dans [[https://docs.weblate.org/en/latest/admin/config.html|celle de Weblate]].


Nous n'oublions pas de créer un dossier ''data'' qui, comme indiqué dans la configuration, stockera tous nos fichiers statiques :

<code>mkdir -p data/media
mkdir -p data/static</code>

Maintenant que tout est prêt, nous pouvons créer la base de données :

<code>pipenv run weblate migrate</code>

<WRAP center round important>La création de la base de donnés nécessite les droits de super-utilisatrice. Ces droits particulièrement dangereux seront ensuite enlevés. Sur PostgreSQL, ces droits se mettent en s'enlèvent de la sorte : ''ALTER USER weblate WITH SUPERUSER;'' et ''ALTER USER weblate WITH NOSUPERUSER;''</WRAP>

Nous pouvons maintenant collecter les fichiers statiques afin de remplir le dossier correspondant :

<code>pipenv run weblate collectstatic</code>

Afin de tester que tout fonctionne, nous pouvons lancer le serveur de debug et accéder à l'URL :

<code>pipenv run weblate runserver 0.0.0.0:8000</code>

<WRAP center round info>Le serveur de debug joue ici à la fois le rôle de nginx et de uWsgi. C'est fort pratique pour vérifier que l'on a bien installé Weblate et donc, en cas d'erreur, savoir si elle provient de l'installation de Weblate ou du déploiement nginx/uWsgi. En revanche, pour des raisons de sécurité, il ne doit surtout pas être utilisé en production. Plus d'informations sur cet outil sont disponibles dans le [[https://docs.djangoproject.com/fr/3.0/ref/django-admin/#runserver|documentation de Django]].</WRAP>

Enfin, si tout fonctionne, nous pouvons créer un compte administratrice sur Weblate :

<code>pipenv run weblate createadmin</code>

<WRAP center round tip>Il se peut que le compte administratrice existe déjà. Dans ce cas, l'identifiant est ''admin'' et vous pouvez changer le mot de passe avec la commande suivante :
<code>pipenv run weblate createadmin --update</code></WRAP>

==== uWsgi ====

Pour une raison inconnue, Debian n'inclue pas de fichiers de service uWsgi avec le paquet. Nous allons donc créer nous-meme le fichier ''/etc/systemd/system/uwsgi-socket@.service'' :

<code>[Unit]
Description=uWSGI service unit
After=syslog.target

[Service]
ExecStart=/usr/bin/uwsgi --ini /etc/uwsgi/%I.ini
ExecReload=/bin/kill -HUP $MAINPID
ExecStop=/bin/kill -INT $MAINPID
Type=notify
SuccessExitStatus=15 17 29 30
StandardError=syslog
NotifyAccess=all
KillSignal=SIGQUIT

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

Ce fichier de service nous permet de lancer différents services uWsgi avec des configurations spécifiques. Pour ce faire, nous créons un fichier ''/etc/uwsgi/weblate.ini'' :

<code>[uwsgi]
uid=khaganat
gid=khaganat
virtualenv=/home/khaganat/weblate/weblate-venv
wsgi-file=/home/khaganat/weblate/weblate-src/wsgi.py
buffer-size=8192
close-on-exec=True
enable-threads=True
master=True
max-requests=5000
pidfile=/tmp/weblate.pid
plugins=python3
protocol=uwsgi
reload-on-rss=250
socket=127.0.0.1:8000
vacuum=True</code>

<WRAP center round important>Pensez à vérifier les valeurs. En fonction de vos choix d'installation, l'utilisatrice (uid) et le groupe (gid) peuvent varier ainsi que le chemin vers le dossier d'installation de Weblate (virtualenv et wsgi-file) voir le fichier de PID (pidfile).</WRAP>

Nous pouvons activer et lancer le service correspondant :

<code>systemctl enable --now uwsgi-socket@weblate.service</code>

<WRAP center round tip>Ce fichier de service peut également gérer d'autres applications uWsgi qui seraient installées sur la même machine. Il suffit alors de créer un nouveau fichier de configuration ''/etc/uwsgi/mon_application.ini'' et d'activer/lancer ''uwsgi-socket@mon_application.service''.</WRAP>

==== nginx ====

Créons le fichier ''/etc/nginx/sites-available/weblate.conf'' :

<code>server {
        listen 192.168.20.39:8000 default_server;
        server_name locale.khaganat.net;

        root /var/www/html;

        location /static/ {
                alias /home/khaganat/weblate/data/static/;
        }

        location /media/ {
                alias /home/khaganat/weblate/data/media/;
        }

        location / {
                include uwsgi_params;
                uwsgi_read_timeout 3600;
                uwsgi_pass 127.0.0.1:8000;
        }
}</code>

<WRAP center round important>Pensez à vérifier les valeurs. En fonction de vos choix d'installation, l'adresse IP et le port d'écoute (listen) peuvent varier ainsi que le chemin vers le dossier de fichiers statiques.</WRAP>

Dans le dossier ''/etc/nginx/sites-enabled'', créons un lien symbolique vers ce fichier afin de l'activer :

<code>ln -s /etc/nginx/sites-available/weblate.conf /etc/nginx/sites-enabled/weblate.conf</code>

Si besoin, désactivons le site par défaut :

<code>rm /etc/nginx/sites-enabled/default</code>

Enfin, redémarons nginx :

<code>systemctl restart nginx.service</code>


===== Mise à jour =====

<WRAP center round alert>Ceci est une procédure théorique qui n'a jamais été utilisée en conditions réelles. Il sera donc nécessaire de la confirmer ou de la corriger après sa première utilisation.</WRAP>

En cas de mise à jour de Weblate et/ou de Python, il faut l'appliquer sur l'environnement virtuel. Une mise à jour de Python rendant généralement ce dernier inutilisable en l'état, la méthode Léodagan est alors recommandée : tout cramer pour repartir sur des bases saines. C'est pour cela que, lors de l'installation, nous avons bien fait attention à différencier :

  * l'environnement virtuel considéré comme jetable
  * la configuration qui est dans un dossier spécifique
  * les fichiers statiques qui sont également dans un dossier spécifique

Et je n'ose pas préciser la base de données qui est, comme tout le monde le sait, un élément totalement à part avec son propre logiciel.

Bref, commençons par arreter uWsgi :

<code>systemctl stop uwsgi-socket@weblate.service</code>

Ensuite, la mise à jour « virile » du virtualenv :

<code>pipenv --rm
pipenv --three install</code>

<WRAP center round important>Si l'environnement virtuel est partagé avec d'autres services, comme par exemple par erreur sur Jukni3, et que Python n'a pas été mis à jour, on se contentera de faire un ''pipenv update'' au lieux de supprimer et recréer le virtualenv.</WRAP>

Comme vu lors de l'installation, il nous faut recréer quelques liens symboliques. Là encore, on détruit pour reconstruire :

<code>rm -f weblate-venv weblate-src
ln -s "$(pipenv --venv)" weblate-venv
ln -s "$(pipenv --venv)/lib/$(pipenv run python -c 'import sys; print(f"python{sys.version_info.major}.{sys.version_info.minor}")')/site-packages/weblate" weblate-src
ln -s "$(pwd)/settings.py" weblate-src/settings.py</code>

Maintenant que la mise à jour est effectuée, nous pouvons relancer uWsgi :

<code>systemctl start uwsgi-socket@weblate.service</code>


===== Lien avec GitLab =====

<WRAP center round alert>Cette section est une ébauche en cours de réalisation. Le lien avec le [[https://git.khaganat.net/|GitLab]] n'est pas encore actif.</WRAP>

Afin de permettre à Weblate de communiquer avec notre gitlab, il faut tout d'abord installer un programme externe : [[https://github.com/zaquestion/lab/|lab]]. Ce paquet devrait arriver prochainement sur Debian sous le nom de [[https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=898246|git-lab]].

Une fois lab installé, il faut créer la configuration dédiée dans le dossier des fichiers statiques. La [[https://docs.weblate.org/en/latest/vcs.html#setting-up-lab|documentation de Weblate]] détaille la base de cette procédure. Il devrait y avoir une option pour spécifier une instance de GitLab autre que l'instance officielle.

Il ne reste plus qu'à actualiser la valeur de ''GITLAB_USERNAME'' dans la configuration de Weblate (''settings.py'').

{{tag>Serveur Web}}