aboutsummaryrefslogtreecommitdiff
path: root/Documentation/usage/installation.rst
blob: 2455996ceaf33401591bbc6896863372059e650e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
===============================
Installation de celcatsanitizer
===============================

Dépendances
===========
celcatsanitizer est écrit en Python 3. Il dépend des bibliothèques
suivantes :

 - `Django 2.0`_
 - requests_, pour récupérer les emplois du temps en HTTP(S)
 - BeautifulSoup4_, pour parser les emplois du temps en XML
 - icalendar_, pour générer des fichiers ICS_.

*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.0: https://www.djangoproject.com/
.. _requests: http://docs.python-requests.org/en/master/
.. _BeautifulSoup4:
  https://www.crummy.com/software/BeautifulSoup/bs4/doc/
.. _icalendar: https://icalendar.readthedocs.io/en/latest/
.. _ICS: https://fr.wikipedia.org/wiki/ICalendar
.. _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``.

celcatsanitizer passera à Django 2.1 lorsqu’il sortira pour utiliser
l’annotation ``TruncWeek``, pour l’instant implémenté avec une requête
SQL brute. Cette fonctionnalité ne sera nécessaire que pour les
utilisateurs de PostgreSQL.

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 ê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

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/

``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".