=============================== Installation de celcatsanitizer =============================== Dépendances =========== celcatsanitizer est écrit en Python 3. Il dépend des bibliothèques suivantes : - `Django 2.2`_ - requests_, pour récupérer les emplois du temps en HTTP(S) - BeautifulSoup4_ et LXML_, pour parser les emplois du temps en XML - icalendar_, pour générer des fichiers ICS_. Une dépendance est optionnelle : - `Django REST Framework`_, pour l’:doc:`API REST `. celcatsanitizer requiert Python 3.6 au minimum. Les versions supérieures devraient fonctionner sans problèmes, mais pas les versions antérieures. *A priori*, il est possible d’utiliser n’importe quel SGBD supporté par Django avec celcatsanitizer. Cependant, l’utilisation de PostgreSQL_ est fortement recommandée. Dans ce cas, vous aurez besoin d’installer le module psycopg2_. Pour l’instant, l’installation doit passer par git_. .. _Django 2.2: https://www.djangoproject.com/ .. _requests: http://docs.python-requests.org/en/master/ .. _BeautifulSoup4: https://www.crummy.com/software/BeautifulSoup/bs4/doc/ .. _LXML: https://lxml.de/ .. _icalendar: https://icalendar.readthedocs.io/en/latest/ .. _ICS: https://fr.wikipedia.org/wiki/ICalendar .. _Django REST Framework: https://www.django-rest-framework.org/ .. _PostgreSQL: https://www.postgresql.org/ .. _psycopg2: http://initd.org/psycopg/docs/install.html .. _git: https://git-scm.com/ Notes sur Django ---------------- celcatsanitizer utilise des versions assez récentes de Django, notamment en ce qui concerne son ORM. Le passage de Django 1.10 à Django 1.11 s’est fait pour utiliser l’annotation ``ExtractWeek``, le passage de Django 1.11 à Django 2.0 pour utiliser l’attribut ``distinct`` de l’aggrégat ``ArrayAgg``. Il utilise l’aggrégat ``TruncWeek`` apparu dans Django 2.1, et se base officiellement sur Django 2.2 pour bénéficier du support à long terme. Installation ============ Création de l’environnement virtuel ----------------------------------- Cette étape est optionnelle, mais est tout de même fortement recommandée. Placez-vous dans le répertoire souhaité, installez l’environnement virtuel, puis activez-le : .. code:: shell $ virtualenv -p python3 celcatsanitizer $ cd celcatsanitizer $ source bin/activate Il est possible que votre version de pip soit ancienne. Si vous le souhaitez, mettez-le à jour : .. code:: shell $ pip install -U pip Installation des dépendances ---------------------------- Vous pouvez demander à ``pip`` d’installer les dépendances à partir du fichier ``requirements.txt`` présent dans le dépôt : .. code:: shell $ pip install -r requirements.txt Cette commande installera aussi ``psycopg2-binary`` et ``gunicorn``. Il est aussi possible d’installer les dépendances à la main : .. code:: shell $ pip install django beautifulsoup4 icalendar requests Si vous utilisez PostgreSQL, vous devez installer le module psycopg2 : .. code:: shell $ pip install psycopg2-binary Si vous souhaitez activer l’API REST, vous devez installer le module Django Rest Framework : .. code:: shell $ pip install djangorestframework Si vous êtes en production, il est recommandé d’utiliser gunicorn_ si vous n’utilisez pas le serveur Apache. Installez-le de la même manière : .. code:: shell $ pip install gunicorn Création du projet Django ------------------------- .. code:: shell $ django-admin startproject celcatsanitizer $ cd celcatsanitizer Récupération des sources de celcatsanitizer ------------------------------------------- .. code:: shell $ git clone https://git.pa1ch.fr/alban/celcatsanitizer.git edt Pour la production, il est recommandé d’utiliser une version stable. Elles sont accessibles à travers les tags git. Configuration de Django ======================= Avant de pouvoir lancer celcatsanitizer, vous allez devoir modifier quelques fichiers. ``settings.py`` --------------- Dans le fichier ``celcatsanitizer/settings.py``, vous devrez renseigner plusieurs informations. Configuration des administrateurs ````````````````````````````````` Vous pouvez retrouver la documentation de la variable ``ADMIN`` `sur le site de Django`__. Cette variable est **obligatoire**. __ https://docs.djangoproject.com/fr/2.0/ref/settings/#admins Configuration de la base de données ``````````````````````````````````` Vous pouvez retrouver la documentation relative à la configuration de la base de données `sur le site de Django`__. Cette étape est **obligatoire**. __ https://docs.djangoproject.com/fr/2.0/ref/settings/#databases Configuration du mode de Django ``````````````````````````````` Si jamais vous utilisez Django en production, vous **devez impérativement** mettre la valeur de la variable ``DEBUG`` à ``False``. Ajout de celcatsanitizer à la liste des applications Django ``````````````````````````````````````````````````````````` Ajoutez la chaîne de caractère ``edt`` à la liste ``INSTALLED_APPS``. Cette étape est **obligatoire**. .. _ref-flatpages: Activation des flatpages ```````````````````````` celcatsanitizer se sert des flatpages pour rendre les pages "contact" et "à propos". Vous pouvez retrouver le guide d’installation `sur le site de Django`__. Effectuez uniquement les deux premières étapes, celcatsanitizer enregistre déjà une route pour les pages statiques, et la commande de l’étape 4 sera effectuée plus loin. Cette étape est **obligatoire**. __ https://docs.djangoproject.com/fr/2.0/ref/contrib/flatpages/#installation Sélection du parseur ```````````````````` celcatsanitizer dispose d’un système de parseurs modulaires depuis la :ref:`version 0.14 `, et embarque par défaut trois parseurs : - ``edt.management.parsers.ups2017``, pour le format utilisé par l’Université Paul Sabatier en 2017. C’est le parseur utilisé par défaut si aucun autre n’est spécifié. Ce parseur utilise BeautifulSoup4_. - ``edt.management.parsers.ups2018``, pour le format utilisé par l’Université Paul Sabatier en 2018. Ce parseur utilise LXML_ et exploite l’IO asynchrone de Python. - ``edt.management.parsers.ups2019``, pour le format utilisé par l’Université Paul Sabatier en 2019. Ce parseur utilise le module JSON standard. Pour spécifier le parseur à utiliser, il faut rajouter une variable ``CS_PARSER``, contenant le parseur à utiliser sous forme de chaîne de caractères. Pour utiliser le parseur ``edt.management.parsers.ups2018``, il faut donc rajouter cette ligne : .. code:: Python CS_PARSERS = "edt.management.parsers.ups2018" Pour l’instant, le parseur est global. Il n’est pas encore possible d’en spécifier un par source d’emploi du temps. Vous **devez** vérifier le format des emplois du temps à parser, cette étape est donc **obligatoire**. Gestion des fichiers statiques `````````````````````````````` Si vous êtes en production, vous devez renseigner l’emplacement de vos fichiers statiques dans la variable ``STATIC_ROOT`` de la configuration de Django (vous pouvez retrouver la documentation correspondante sur le site de Django). Cette étape est **obligatoire en production**, mais inutile en déboguage. Ajout du processeur de contexte de celcatsanitizer `````````````````````````````````````````````````` Rajoutez la chaîne de caractères ``edt.views.ctx_processor`` à la liste ``context_processors`` dans la variable ``TEMPLATES``. Cette étape est **fortement recommandée**. Configuration de l’internationalisation ``````````````````````````````````````` Vous pouvez retrouver la documentation de l’internationalisation `sur le site de Django`__. Ce paramètre est **optionnel**. __ https://docs.djangoproject.com/fr/2.0/topics/i18n/ Activation de l’API REST et configuration de Django Rest Framework `````````````````````````````````````````````````````````````````` L’API REST permet à des outils tiers d’accéder facilement aux données gérées par celcatsanitizer. Elle est optionnelle, et est basée sur Django Rest Framework. :doc:`Plus d’informations sur la page de l’API REST `. Si vous souhaitez l’activer, vous devez d’abord avoir installé Django REST Framework, puis mettre la variable ``CS_ENABLE_API`` à ``True``. .. code:: Python CS_ENABLE_API = True Ajoutez ensuite la chaîne de caractère ``rest_framework`` à la liste ``INSTALLED_APPS``. Libre à vous de configurer DRF de la manière dont vous le souhaitez. `Les différents paramètres sont accessibles ici`__. Les plus intéressants sont ``DEFAULT_PERMISSION_CLASSES``, ``DEFAULT_RENDERER_CLASSES``, ``DEFAULT_PAGINATION_CLASS`` et ``PAGE_SIZE``. __ https://www.django-rest-framework.org/api-guide/settings/ Cette étape est **optionnelle**. ``urls.py`` ----------- Dans le fichier ``celcatsanitizer/urls.py``, importez la fonction ``django.conf.urls.include`` si elle ne l’est pas déjà, et rajouter ``url(r'^', include("edt.urls"))`` à la *fin* de la liste ``urlspatterns``. Cette étape est **obligatoire**. Derniers préparatifs ==================== Génération de la base de données -------------------------------- Générez les migrations de Django et de celcatsanitizer, puis appliquez-les : .. code:: shell $ ./manage.py makemigrations edt $ ./manage.py migrate Collection des fichiers statiques --------------------------------- Si vous êtes en production, il faut regrouper les fichiers statiques. Pour ce faire, exécutez la commande suivante : .. code:: shell $ ./manage.py collectstatic Cette étape est **obligatoire** en production, mais inutile en déboguage. Création d’un super-utilisateur ------------------------------- Pour pouvoir accéder à l’interface d’administration, il est important de créer un super-utilisateur. Pour cela, exécutez la commande suivante : .. code:: shell $ ./manage.py createsuperuser Répondez ensuite aux questions posées. Cette étape est **fortement recommandée**. .. _ref-cron: Cron ---- Pour mettre à jour les emplois du temps de manière régulière, il faut rajouter :doc:`la commande de mise à jour ` dans une tâche cron. Lancement ========= En mode de déboguage -------------------- Exécutez tout simplement la commande suivante : .. code:: shell $ ./manage.py runserver En production ------------- Le serveur intégré à Django n’est pas adapté pour un usage en production. Il vaut mieux utiliser Apache avec mod_wsgi, ou avec un serveur gunicorn_ derrière nginx_. .. _gunicorn: https://gunicorn.org/ .. _nginx: https://nginx.org/en/ Ajout des pages statiques ========================= :ref:`Comme indiqué plus haut `, celcatsanitizer fait appel aux flatpages de Django. À l’aide de l’interface d’administration de Django (si votre instance se trouve à l’adresse ``example.com``, vous pourrez y accéder à l’adresse ``example.com/admin``), dans la section "pages statiques", rajoutez les pages ``/a-propos/`` et ``/contact/``. Si vous êtes en production, changez le site de base (``example.com``) par le site sur lequel se trouvera votre instance de celcatsanitizer, trouvable dans la section "sites".