Installation
L'application Guidon s'exécute dans des conteneurs docker. La meilleure façon d'utiliser Guidon est de l'héberger sur sa propre infrastructure technique.
Un service payant d'hébergement pourra être proposé à l'avenir pour les organisations qui ne peuvent pas déployer Guidon sur leur propre infrastructure.
Prérequis de l'application Guidon
Un serveur avec docker version 19.10 et docker-compose version 1.19.0 minimum.
L'accès au service nécessite aussi un serveur web pour transmettre les requêtes entrantes à l'application Guidon. Ce serveur web en tant que serveur mandataire inverse. Ces deux composants de l'infrastructure technique peuvent très bien être sur le même serveur physique.
L'installation de Guidon nécessite trois fichiers :
- un fichier
docker-compose.yml, qui contient la définition des différents conteneurs à configurer et exécuter - un fichier
nginx.conf.template, qui contient la configuration du serveur nginx interne à Guidon, qui route les requêtes vers les différents conteneurs - un fichier
.env, qui contient les principaux paramètres techniques de l'application
Installation de l'application
Résumé
En résumé, il est possible d'installer et lancer Guidon avec la suite de commandes ci-dessous. Les détails sont expliqués dans les sections suivantes.
curl -o docker-compose.yml https://gitlab.com/guidonapp/guidon/-/raw/main/docker-compose.yml
curl -o nginx.conf.template https://gitlab.com/guidonapp/guidon/-/raw/main/frontend/nginx/templates/default.conf.template
curl -o .env https://gitlab.com/guidonapp/guidon/-/raw/main/.env.example
# Editer .env and configurer les variables du premier bloc
vim .env
docker-compose up -d
Téléchargement du fichier exemple docker-compose.yml
Un exemple de fichier docker-compose.yml est disponible à la racine du dépôt Gitlab de Guidon depuis cette adresse : (https://gitlab.com/guidonapp/guidon/-/blob/main/docker-compose.yml).
Ce fichier, dans la branche main, pointe toujours sur la dernière version stable officielle de Guidon. A priori, il n'y aucune modification à apporter à ce fichier.
Téléchargement du fichier nginx.conf.template
Ce fichier est ici encore disponible dans le dépôt Gitlab de Guidon. Il n'y a pas de
raison de le modifier. Ce fichier est référencé par le fichier docker-compose.yml.
Le nom nginx.conf.template doit être conservé.
Téléchargement du fichier exemple .env.example
Ce fichier contient toutes les variables qui permettent la configuration technique de Guidon. Seules celles du premier bloc sont obligatoires pour le bon fonctionnement de l'application.
De même que pour le fichier docker-compose.yml, un fichier exemple
.env.example se trouve à la racine du dépôt Gitlab de Guidon, à cette
adresse :
(https://gitlab.com/guidonapp/guidon/-/blob/main/.env.example).
Une fois téléchargé, celui-ci doit être renommé en .env avant d'être renseigné.
Edition du fichier .env
# Le nom du site par lequel on accède à l'application
GUIDON_EXTRA_ALLOWED_HOSTS=mon.site.net
# doit contenir une chaine de caractères aléatoire, unique pour chaque instance de guidon
SECRET_KEY=
DATABASE_ENGINE=django.db.backends.postgresql
DATABASE_NAME=guidon # à changer si besoin
DATABASE_USER=guidon # à changer si besoin
# mot de passe de connexion à la base de données
DATABASE_PASSWORD=
# L'adresse pour accéder au site
GUIDON_PUBLIC_URL=https://mon.site.net
Génération du secret
Il est possible de générer un secret avec l'instruction suivante, executée dans un shell avec python >= 3.6 installé :
Lancement de l'application
Une fois les deux fichiers téléchargés et édités, l'application peut se lancer avec la commande standard de docker-compose :
Installation de Guidon derrière un serveur mandataire inverse
L'accès à Guidon depuis une adresse internet publique nécessite qu'un serveur web recevant ce trafic le route vers l'application Guidon elle-même.
Installation de Guidon derrière Apache
Prérequis
On installe les modules Apache nécessaires et on redémarre :
Fichier de configuration Apache
En supposant que l'adresse publique de Guidon est mon.site.net, voici le fichier de configuration Apache correspondant :
<VirtualHost *:80>
ServerName mon.site.net
Redirect / https://mon.site.net
</VirtualHost>
<IfModule mod_ssl.c>
<VirtualHost _default_:443>
ServerName mon.site.net:443
# ajouter les autres instructions, notamment la configuration SSL
ProxyPreserveHost On
<Location "/">
Require all granted
ProxyPass http://127.0.0.1:8100/
ProxyPassReverse http://127.0.0.1:8100/
ProxyPassReverseCookieDomain 127.0.0.1 mon.site.net
</Location>
</VirtualHost>
</IfModule>
Sauvegarde et restauration de Guidon
Dans la version actuelle de Guidon, les données sont exclusivement stockées en base de données. La sauvegarde de l'application consiste en la sauvegarde de la base de données. Il en va de même pour la restauration.
Sauvegarde des données
Les instructions suivantes créent un fichier de sauvegarde daté en supposant que les noms des conteneurs docker sont ceux du fichier docker-compose.yml fourni par défaut. L'arrêt préalable des conteneurs du frontend et du backend permet une sauvegarde sans risque de modification concurrente.
# (optionnel) arrêt des conteneurs du frontend et du backend
docker container stop guidon_frontend guidon_backend
# création du fichier de sauvegarde
docker exec guidon_db pg_dump -Fc -h localhost -U guidon -d guidon -f guidon_`date +"%Y%m%d"`.dump
# copie du fichier de sauvegarde du conteneur vers l'hôte
docker cp guidon_db:/guidon_`date +"%Y%m%d"`.dump .
# (optionnel) relance des conteneurs du frontend et du backend depuis
# le répertoire contenant les fichiers docker-compose.yml et .env
docker-compose up -d
Restauration des données
De même, la restauration des données peut se faire à chaud ou à froid suivant les heures d'utilisation de l'application.
Si la sauvegarde restaurée correspond à une version antérieure à la version installée, il faut impérativement arrêter le backend et le relancer après la restauration pour que la structure de la base de données puisse être mise à jour (automatique au lancement du conteneur du backend).
Dans les instructions qui suivent, on suppose que le fichier de sauvegarde se nomme guidon_AAAAMMJJ.dump.
# arrêt des conteneurs du frontend et du backend
docker container stop guidon_frontend guidon_backend
# copie du fichier de sauvegarde de l'h$ôte vers le conteneur
docker cp ./guidon_AAAAMMJJ.dump guidon_db:/
# restauration de la sauvegarde
docker exec guidon_db pg_restore -Cc -d postgres -h localhost -U guidon guidon_AAAAMMJJ.dump
# relance des conteneurs du frontend et du backend depuis
# le répertoire contenant les fichiers docker-compose.yml et .env
docker-compose up -d
Accéder aux logs de l'application
Les logs applicatifs les plus pertinents sont ceux du backend. Voilà une commande qui permet d'afficher les derniers logs tout en laissant l'affichage se mettre à jour en cas de nouvelle entrée.
Les logs montrent :
- la mise à jour de la base de données (si nécessaire) au lancement du conteneur du backend
- les requêtes HTTP recues
- les erreurs non correctement gérées par l'application, venant probablement d'un bug