]> nos-oignons.net Git - gestion-adh.git/blob - README
résolution conflit
[gestion-adh.git] / README
1 ====================================
2 Gestion des adhésions de Nos oignons
3 ====================================
4
5 Voici une collection de scripts et de bouts de code qui permettent de gérer les
6 adhésions de Nos oignons conformément aux statuts de l'association.
7
8 Base des membres
9 ================
10
11 La base des membres est pensée pour être stockée dans le wiki du conseil
12 d'administration. Elle est formée d'une série de pages, une par membre.
13
14 Cela donne l'aboresence suivante :
15
16     Membres
17     ├── 000000.mdwn
18     ├── 000001.mdwn
19     ├── 000002.mdwn
20     ├── 000003.mdwn
21     ├── 000004.mdwn
22     …
23     └── 000042.mdwn
24
25 Chaque page doit ressembler à :
26
27     ---
28     name: Violette Dupuis
29     address: |
30       42 rue du Fleuve
31       12042 Essaiville
32     email: violette@example.org
33     joined_on: 2013-05-25
34     membership_fee_paid_on: 2013-05-25
35     ---
36
37     Violette sait programmer en Ruby, on peut lui demander si on a besoin de
38     coup de main.
39
40 Le début de chaque page est un morceau de [YAML]. Il doit contenir les entrées
41 suivantes :
42
43 =`name`=
44     Le nom (complet) du membre.
45
46 =`address`=
47     L'adresse postale du membre.
48
49 =`email`=
50     L'adresse email du membre. C'est à cette adresse que seront envoyés les
51     messages de l'assemblée générale et les rappels de cotisation.
52
53 =`joined_on`=
54     Date d'adhésion à l'association.
55
56 =`membership_fee_paid_on`=
57     Date du paiement de la dernière cotisation.
58
59 Le reste de la page peut servir à noter ce qu'on veut.
60
61 [YAML]: http://yaml.org/
62
63 Scripts
64 =======
65
66 Voici le détail des scripts utilisés. On peut se faire une idée de leurs
67 fonctionalités respectives en lisant les cas d'utilisation dans les fichiers
68 `features/*.feature`.
69
70 Le chemin vers la racine du clone du wiki du conseil d'amnisitration est
71 spécifié par la variable d'environnement `NOS_OIGNONS_BOARD_WIKI_PATH`. Si
72 cette dernière n'est pas spécifiée, les scripts cherchent un répertoire
73 `Membres` à la racine du Git courant, et si ce n'est pas le cas, dans
74 le répertoire `wiki-ca` du répertoire parent du Git courant.
75
76 `list-email`
77 ------------
78
79 Affiche sur la sortie standard les adresses emails des membres à jour de
80 cotisation.
81
82 `pre-commit-hook`
83 -----------------
84
85 `pre-commit` hook pour Git. Ce dernier est avant tout là pour éviter de pouvoir
86 enregistrer des informations invalides dans la base des membres depuis Ikiwiki.
87 Il est nécessaire de le configurer à chaque fois qu'on clone le dépôt du wiki du
88 C.A. (en faisant un lien symbolique dans `.git/hooks/pre-commit`).
89
90 `pre-receive-hook`
91 ------------------
92
93 `pre-receive` hook pour Git. Ce dernier est là pour éviter de pouvoir enregistrer
94 des informations invalides dans la base des membres. Il doit être configuré dans
95 le dépôt central du wiki du C.A. (via un lien symbolique dans
96 `.git/hooks/pre-receive`).
97
98 `update-ag-subscribers`
99 -----------------------
100
101 Met à jour la liste des adresses email inscrites à la liste *ag@* par rapport
102 aux membres à jour de cotisation. À exécuter à travers un *cron*. A besoin de
103 pouvoir se connecter à l’API REST de Mailman 3.
104
105 La variable d’environnement suivante doit être
106 définie `NOS_OIGNONS_MAILMAN_REST_API_URL` avec par exemple :
107 `https://user:password@mailman.example.org`
108
109 À défaut, cette dernière sera lue depuis le fichier `mailman-rest-url`
110 dans le dossier indiqué par la variable d’environnemnet `CREDENTIALS_DIRECTORY`
111 (voir [System and Service Credentials](https://systemd.io/CREDENTIALS/) et
112 la procédure de déploiement indiqué plus bas).
113
114 `send-membership-reminders`
115 ---------------------------
116
117 Préviens les membres qu'il faut renouveler leur cotisation.
118
119 Le fichier utilisé pour garder la liste des envois déjà effectués est soit
120 celui indiqué par la variable d'environnement `NOS_OIGNONS_REMINDER_DB`, soit
121 le fichier `var/reminders.yaml` si la variable est vide.
122
123 `send-member-emails-to-advisors`
124 --------------------------------
125
126 Envoie la liste des emails des membres à jour de cotisation au comité
127 de déontologie.
128
129 Ce script a vocation a être executé tous les mois afin que le comité
130 puisse convoquer une assemblée générale extraordinaire, même en cas de
131 défaillance du conseil d'administration.
132
133 `create-membership-fee-receipt`
134 -------------------------------
135
136 Permet de créer un reçu de cotisation pour les membres en faisant
137 la demande.
138
139 Exemple d'utilisation :
140
141     bin/create-membership-fee-receipt 000042 10,00
142
143 Cela crééra un reçu pour le membre 000042 pour une cotisation d'un montant
144 de 10,00€. Le reçu est généré sous forme d'un fichier PDF dans le répertoire
145 spécifié par la variable d'environnement NOS_OIGNONS_RECEIPTS_DIR (ou le
146 répertoire `receipts` dans le répertoire courant).
147
148 **Il faut créer le répertoire avant utilisation s'il n'existe pas déjà.**
149
150 Développement
151 =============
152
153 L'essentiel du code est en Ruby. Les dépendances sont gérées avec Bundler. Les
154 tests d'intégrations sont faits avec Cucumber.
155
156 Installer les paquets Debian qui vont bien (sur Jessie) :
157
158     apt-get install bundler
159
160 Pour récupérer les dépendances :
161
162     bundle install --path=vendor/bundle
163
164 Déploiement
165 ===========
166
167 Installer les paquets Debian qui vont bien (sur Wheezy) :
168
169     apt-get install bundler
170
171 Installer les dépendances :
172
173     bundle install --deployment --without=development --path=vendor/bundle
174     chmod -R o+rX vendor/bundle
175
176 Il faut donner les droits d'écriture à `wiki-ca` sur le répertoire `var`.
177
178 Pour rendre facilement accessible `list-members-emails`, on peut ajouter dans
179 `/usr/local/bin` un mini script tel que celui-ci :
180
181     #!/bin/sh
182     NOS_OIGNONS_BOARD_WIKI_PATH=/srv/ikiwiki/wiki-ca/src \
183         /srv/ikiwiki/wiki-ca/gestion-adh/bin/list-emails
184
185 Ne pas oublier de le rendre exécutable.
186
187 On va utiliser des
188 [services](https://www.freedesktop.org/software/systemd/man/systemd.service.html)
189 et des [timers](https://www.freedesktop.org/software/systemd/man/systemd.timer.html)
190 systemd pour les scripts à utiliser régulièrement.
191
192 Dans `/etc/systemd/system/gestion-adh-update-ag-subscribers.service` :
193
194     [Unit]
195     Description=Update subscribers of the `ag` mailing list according to memberships
196
197     [Service]
198     Type=oneshot
199     WorkingDirectory=/srv/ikiwiki/wiki-ca/gestion-adh
200     User=wiki-ca
201     ExecStart=/srv/ikiwiki/wiki-ca/gestion-adh/bin/update-ag-subscribers
202     Environment=BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile NOS_OIGNONS_BOARD_WIKI_PATH=/srv/ikiwiki/wiki-ca/src
203     SyslogIdentifier=update-ag-subscribers
204     ProtectSystem=strict
205     ProtectHome=true
206     PrivateTmp=yes
207     PrivateDevices=yes
208
209 Dans `/etc/systemd/system/gestion-adh-update-ag-subscribers.timer` :
210
211     [Unit]
212     Description=Run update-ag-subscribers every hour
213
214     [Timer]
215     RandomizedDelaySec=30min
216     OnCalendar=hourly
217
218     [Install]
219     WantedBy=timers.target
220
221 Il est également nécessaire de configurer le *credential* avec les informations
222 de connexion à Mailman :
223
224     echo -n 'https://USER:SECRET_PASSWORD@localhost:8001' | sudo systemd-creds encrypt --name=mailman-rest-url -p - - | sudo tee -a /etc/systemd/system/gestion-adh-update-subscribers.service.d/overrides.conf
225
226 Dans `/etc/systemd/system/gestion-adh-send-membership-reminders.service` :
227
228     [Unit]
229     Description=Send reminders to renew membership
230
231     [Service]
232     Type=oneshot
233     WorkingDirectory=/srv/ikiwiki/wiki-ca/gestion-adh
234     User=wiki-ca
235     ExecStart=/srv/ikiwiki/wiki-ca/gestion-adh/bin/send-membership-reminders
236     Environment=BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile NOS_OIGNONS_BOARD_WIKI_PATH=/srv/ikiwiki/wiki-ca/src
237     SyslogIdentifier=send-membership-reminders
238     ProtectSystem=strict
239     ProtectHome=true
240     PrivateTmp=yes
241     PrivateDevices=yes
242     ReadWritePaths=/srv/ikiwiki/wiki-ca/gestion-adh/var
243
244 Dans `/etc/systemd/system/gestion-adh-send-membership-reminders.timer` :
245
246     [Unit]
247     Description=Run send-membership-reminders every day
248
249     [Timer]
250     OnCalendar=06:42
251
252     [Install]
253     WantedBy=timers.target
254
255 Dans `/etc/systemd/system/gestion-adh-send-member-emails-to-advisors.service` :
256
257     [Unit]
258     Description=Send member emails to the advisory board
259
260     [Service]
261     Type=oneshot
262     WorkingDirectory=/srv/ikiwiki/wiki-ca/gestion-adh
263     User=wiki-ca
264     ExecStart=/srv/ikiwiki/wiki-ca/gestion-adh/bin/send-member-emails-to-advisors
265     Environment=BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile NOS_OIGNONS_BOARD_WIKI_PATH=/srv/ikiwiki/wiki-ca/src
266     SyslogIdentifier=send-member-emails-to-advisors
267     ProtectSystem=strict
268     ProtectHome=true
269     PrivateTmp=yes
270     PrivateDevices=yes
271
272 Dans `/etc/systemd/system/gestion-adh-send-member-emails-to-advisors.timer` :
273
274     [Unit]
275     Description=Run send-member-emails-to-advisors monthly
276
277     [Timer]
278     OnCalendar=monthly
279
280     [Install]
281     WantedBy=timers.target
282
283 Pour installer le `pre-commit` *hook* sur le dépôt utilisé par
284 Ikiwiki, on met dans `/srv/ikiwiki/wiki-ca/src/.git/hooks/pre-commit` :
285
286     if ! BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile /srv/ikiwiki/wiki-ca/gestion-adh/bin/pre-commit-hook; then
287             # Reset changes that do not pass the pre-commit hook to prevent
288             # wrong changes to lay in the Ikiwiki source directory.
289             git reset --hard
290             exit 1
291     fi
292
293 Ne pas oublier de le rendre exécutable.
294
295 Pour installer le `pre-receive` *hook* sur le dépôt central, on met dans
296 `/srv/git/.gitolite/hooks/wiki-ca/hooks/pre-receive` :
297
298     #!/bin/sh
299     BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile /srv/ikiwiki/wiki-ca/gestion-adh/bin/pre-receive-hook
300
301 Ne pas oublier de le rendre exécutable. Il faut ensuite faire un lien symbolique :
302
303     ln -s ../../../.gitolite/hooks/wiki-ca/pre-receive /srv/git/repositories/wiki-ca.git/hooks/pre-receive
304
305 Licences
306 ========
307
308 Système de gestion des adhésions de Nos oignons  
309 Copyright © 2013-2014 Nos oignons <contact@nos-oignons.net>  
310 Licence : GNU AGPLv3 ou ultérieur, voir `LICENCE`
311
312 Police OpenSans  
313 Copyright © 2010-2011, Google Corporation  
314 Licence : Apache 2.0, voir `share/fonts/OpenSans/Apache-2.0`
315
316 Logo Nos oignons  
317 Copyright © 2013 lutopiquant  
318 Licence : CC BY-SA 3.0 FR, voir <https://creativecommons.org/licenses/by-sa/3.0/fr/deed.fr>