path: root/Documentation/usage/installation.rst

===============================
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 <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 <ref-ver-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 <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 <commands/timetables>` 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 <ref-flatpages>`, 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".