Ceci est un tutoriel pour mettre en place un environnement de développement local, nécessaire pour faire des tests et des vérifications quand on édite le code de la v5. Si vous n'êtes pas familiers avec Linux, vous pouvez utiliser la machine virtuelle de Dark Storm.
Note : Ce tutoriel a besoin d'être complété. Veuillez ne le suivre pour l'instant que si vous êtes expérimenté.
- Il faut tester sur plusieurs machines réelles.
- Comme il n'y a pas encore de scripts sur le dépôt, on brasse du vent dans les noms de fichiers.
- Il faut fournir une base de données de test.
- Certaines modifications vont affecter le dépôt git, ce qu'il faut éviter à tout prix.
Préliminaires
Pour ce tutoriel, je suppose que vous disposez :
- D'une machine sous Linux (ici, Ubuntu)
- Des droits administrateurs
- De connaissances préalables sur l'utilisation de la ligne de commande
Si vous ne comprenez pas tout ce qui se passe ici, ce n'est pas grave ! Parlez-en sur le forum, on pourra vous expliquer et vous aider à vous sortir d'une situation périlleuse.
Installation de nginx et de pip3
On va commencer par configurer le serveur web, nginx. Le serveur web va écouter les connexions (requêtes) qui entreront sur votre ordinateur et va leur envoyer des réponses (pages web). Bien sûr, tant que vous développez sur votre machine, seuls vous pouvez faire des requêtes à votre serveur web. Le monde extérieur n'aura pas accès à votre machine.
Commencez par installer le paquet nginx. J'en profite pour vous faire installer pip3, un programme qui permet d'installer des modules Python, et virtualenv, dont on aura besoin plus tard.
$ sudo apt-get update
$ sudo apt-get install nginx
$ sudo apt-get install python3-pip virtualenv
Si le serveur web ne démarre pas tout seul, vous devrez le lancer à la main :
$ sudo systemctl start nginx
Configuration du serveur nginx
Nous allons maintenant indiquer à nginx qu'il doit gérer un site web. Rendez-vous dans le répertoire /etc/nginx/sites-available, dont chaque fichier représente un site à gérer. Commencez par supprimer le fichier default, puis créez un nouveau fichier sous le nom planete-casio-v5 et ouvrez-le dans un éditeur de texte. Attention, il vous faudra les droits root pour ça !
$ cd /etc/nginx/sites-available
$ sudo rm default
$ sudo gedit planete-casio-v5
Voilà ce qu'on va mettre dans le fichier de configuration :
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
access_log /var/log/nginx/v5_access.log;
error_log /var/log/nginx/v5_error.log;
root /var/www/v5;
location /static {
try_files $uri =404;
}
location / {
try_files @fake @application;
}
location @application {
include uwsgi_params;
uwsgi_pass unix:/tmp/uwsgi_v5.sock;
}
}
C'est un peu long, mais je vais expliquer brièvement à quoi tout cela sert. Le bloc server délimite notre nouveau site. Les lignes listen disent à nginx d'écouter sur le « port » numéro 80 de votre ordinateur, car c'est là que les navigateurs web envoient les requêtes HTTP. Le champ server_name sert à différencier les sites quand un même ordinateur gère plusieurs sites ; vous n'en avez pas besoin, ou alors vous savez probablement comment faire pour ajuster la configuration. 😁
Les deux lignes suivantes indiquent que toutes les requêtes faites au site doivent être enregistrées dans le fichier /var/log/nginx/v5_access.log et que toutes les erreurs doivent être mises dans /var/log/nginx/v5_error.log. Si quelque chose ne fonctionne pas, consultez le second fichier. Si vous posez une question, incluez toujours les dernières lignes du log d'erreur pour aider ceux qui vous répondront !
La ligne root est très importante. Vous devez indiquer ici le dossier dans lequel vous avez clôné le dépôt Git de la v5. Ce n'est pas forcément /var/www/v5, qui est celui utilisé par le VPS. Remplacez-le par le bon chemin !
La suite dit à nginx que toutes les URLs qui commencent par /static parlent de fichiers sur le disque dur et qu'il doit répondre à la requêtes en envoyant les fichiers. Toutes les requêtes vers des URLs qui ne commencent pas par /static sont envoyées dans un « socket » /tmp/uwsgi_v5.sock, et ça on verra plus tard à quoi ça sert.
Vous pouvez maintenant enregistrer ce fichier et quitter l'éditeur. Le site n'est pas automatiquement « activé » ; pour cela il faut se rendre dans le dossier /etc/nginx/sites-enabled et ajouter un lien (symbolique) vers notre fichier de configuration.
$ cd /etc/nginx/sites-enabled
$ sudo ln -s ../sites-available/planete-casio-v5 planete-casio-v5
Ensuite, il faut demander à nginx (qui est en train de travailler en arrière-plan, même s'il n'a aucun site à gérer) de recharger sa configuration puisqu'on vient d'ajouter un site.
$ sudo systemctl reload nginx
Prenez n'importe quel fichier du dossier static dans le dépôt de la v5, par exemple truc.txt (j'improvise parce qu'il n'y en a pas encore au moment où je rédige ce tutoriel), et visitez l'URL http://localhost/static/truc.txt. Vous devez voir les contenus du fichier s'afficher dans votre navigateur, vous signalant que tout marche bien !
Configuration de l'environnement virtuel
Le serveur web que vous avez actuellement est très sympathique, mais il ne peut présenter que des fichiers et des pages web déjà écrits à l'avance. On aimerait pouvoir générer les pages avec un programme Python pour afficher les derniers commentaires ou les derniers messages de la shoutbox, par exemple. Pour cela, il faudrait que le serveur nginx appelle notre programme, que notre programme lui réponde avec des contenus générés dynamiquement, et que le serveur nginx transfère ces contenus au navigateur qui a fait la requête.
C'est exactement ce qu'on est partis pour faire. Toutes les URLs qui ne commencent pas par /static sont actuellement envoyées par nginx dans un système de communication appelé socket. Un socket est bidirectionnel ; on a branché nginx à un bout. Il nous reste à brancher Python de l'autre et la communication entre les deux donnera naissance à un super site web !
Rendez-vous dans le répertoire où vous avez clôné le dépôt de la v5. On va y configurer Python et Flask (un framework web avec lequel la v5 est développé) pour qu'ils écoutent à l'autre bout de notre socket. Afin de ne pas déranger ce qui se passe d'autre sur votre machine, on va le faire dans un environnement séparé appelé environnement virtuel ou virtualenv pour les anglais.
Créons tout de suite un environnement virtuel dans le dépôt de la v5. La commande suivante crée un environnement virtual dans le répertoire venv.
$ virtualenv -p python3 venv
Ce qui suit est très important. Vous allez pouvoir rentrer dans l'environnement virtuel en l'activant. Pour cela, chargez le script activate qui est fourni avec l'environnement virtuel :
$ source venv/bin/activate
(venv) $
Comme vous pouvez le voir votre prompt change légèrement et est maintenant précédé de la mention (venv) pour vous rappeler que vous êtes dans l'environnement virtuel. Et puisque vous y êtes, vous allez pouvoir y installer deux composants essentiels, Flask et uWSGI. Normalement vous n'avez plus besoin des droits root parce que l'environnement virtuel est situé dans vos fichiers à vous et pas dans ceux du système. En plus de ça, on installe un certain nombre de modules Flask utilisés par la v5.
$ pip3 install flask
$ pip3 install uwsgi
(venv) $ pip3 install flask-login flask-migrate flask-script flask-sqlalchemy flask-wtf flask-mail flask-crontab python-dotenv psycopg2 python-slugify python-ldap Pillow email_validator pyyaml markdown bleach
# Optionnel
(venv) $ pip3 install flask-debugtoolbar
Flask est un framework qui nous aide à créer un site web. Il fait la plupart du boulot pour nous : il génère du HTML, il gère la base de données, la connexion des membres, toutes les URLs qui ne commencent pas par /static, et plein d'autres choses. Quant à uWSGI, c'est le composant que l'on va mettre en sortie du socket où nginx envoie ses requêtes. uWSGI va se brancher sur le socket puis va lancer nos programmes Python avec Flask chaque fois qu'il y en aura besoin !
Configuration de uWSGI
Comme vous avez clôné le dépôt de la v5, les programmes Flask sont déjà écrits. Ce tutoriel ne parle pas de programmation Flask ; voyez ailleurs sur le Wiki, ou le forum, pour trouver des références. Nous, on va juste configurer uWSGI pour qu'il fasse tout ça proprement.
Vous allez devoir ajouter à votre dépôt, à côté de votre environnement virtuel, des fichiers pour ça. Créez un fichier uwsgi.ini pour indiquer à uWSGI de quelle façon il doit se brancher sur le socket. Dans les environnements que j'utilise, il contient les lignes suivantes :
[uwsgi]
uid = www-data
gid = www-data
chmod-socket = 666
Vous devrez peut-être changer le nom d'utilisateur (www-data) selon votre système. Il vous faut ensuite un script run.sh qui permet de lancer uWSGI. Mettez-y quelque chose dans le ton suivant :
#! /bin/sh
cd /var/www/v5
uwsgi -s /tmp/uwsgi_v5.sock --manage-script-name --mount /=app:app --virtualenv=venv --master --ini=uwsgi.ini
Vous devez changer, dans la ligne qui commence par cd, le répertoire /var/www/v5 par le répertoire où vous avez clôné le dépôt de la v5. C'est celui qui contient le répertoire de tout à l'heure.
Je ne détaille pas toutes les options, mais on est en train de boucler la boucle :
-s /tmp/uwsgi_v5.sockindique à uWSGI où est notre socket ;--mount /=main:appdit que l'URL/(le site web) est géré par l'application Flask qui est dans la variableappdemain.py;--virtualenv=venvindique que l'on travaille dans un environnement virtuel qui est dans le dossiervenv;--ini=uwsgi.inimentionne le fichier de tout à l'heure qui contient d'autres paramètres.
Notez que ces deux fichiers sont mentionnés dans le .gitignore du dépôt Git donc ils seront ignorés par Git même s'ils sont dans le dossier du dépôt sur votre ordinateur. Comme uWSGI va gérer l'environnement virtuel tout seul, vous pouvez le désactiver. Normalement vous n'aurez plus besoin d'y retourner.
$ deactivate
Lancez votre nouveau script run.sh. Si tout se passe bien, il va charger l'application et se brancher sur le socket. Vous pouvez maintenant visiter http://localhost et tester la v5 en live ! Appuyez sur Ctrl+C pour arrêter uWSGI quand vous avez fini. Vous ne pourrez alors plus voir que les fichiers statiques, comme avant. Le site ne tourne vraiment que lorsque uWSGI est lancé.
Configuration de la base de données PostgreSQL
Installez PostgreSQL: les paquets sont postgresql (le SGBD) et psycopg2 (bibliothèque Python pour y accéder par Flask) sous Arch, certainement pas différents sur les dérivés d'Ubuntu.
Ensuite connectez-vous en tant qu'utilisateur postgres, qui est l'administrateur de tout le système PostgreSQL. Vous devrez initialiser le stockage de base de données et créer un nouvel utilisateur avec des droits restreints. Je vous suggère de le nommer comme votre compte utilisateur.
lephe$ sudo -ui postgres
postgres$ initdb -D /var/lib/postgres/data
postgres$ createuser lephe
Ensuite créez une base de données dont le nouvel utilisateur sera le propriétaire.
postgres$ createdb -O lephe pcv5
Quittez votre connexion en tant que postgres et démarrez/activez le SGBD dans votre gestionnaire d'init.
postgres$ exit
lephe$ sudo systemctl start postgresql
lephe$ sudo systemctl enable postgresql
Vous pouvez ensuite lancer le shell PostgreSQL pour manipuler votre base de données :
lephe$ psql -d pcv5
Si votre utilisateur PostgreSQL ne s'appelle pas comme votre compte Linux, ajoutez -U <utilisateur>.
Ensuite, dans le script config.py du dépôt, configurez l'accès à la bdd :
SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL') or \
'postgresql+psycopg2://' + os.environ.get('USER') + ':@/pcv5'
Ce code, qui est présent sur le dépôt, marchera automatiquement si vous avez choisi un nom d'utilisateur identique à votre nom de compte. (Sinon on pourra rajouter une variable d'environnement pour personnaliser.)
Lancer le serveur les fois suivantes
Assurez vous que Nginx et PostgreSQL soit bien lancé et opérationnels. Si ils ne sont pas lancé les commandes suivantes devrait suffire à les faire démarrer.
$ sudo systemctl start postgresql
$ sudo systemctl start nginx
Puis exécutez le script run.sh