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>