Switch to Mailman 3 REST API for “ag” subscriptions

[gestion-adh.git] / README

diff --git a/README b/README
index 96cdd549d7cc6a08cfb3174c32958d638360a38c..123a38ad591bc0d6749230ce815fb0efcd8fec1b 100644 (file)
--- a/README
+++ b/README
@@ -8,9 +8,8 @@ adhésions de Nos oignons conformément aux statuts de l'association.
 Base des membres
 ================
 
 Base des membres
 ================
 

-La base des membres est pensée pour être stockés dans le wiki du conseil
-d'administration. Elle est formée sous forme d'une série de pages, une par
-membre.
+La base des membres est pensée pour être stockée dans le wiki du conseil
+d'administration. Elle est formée d'une série de pages, une par membre.

 
 Cela donne l'aboresence suivante :
 
 
 Cela donne l'aboresence suivante :
 


@@ -43,13 +42,17 @@ suivantes :
 
 =`name`=
     Le nom (complet) du membre.
 
 =`name`=
     Le nom (complet) du membre.

+

 =`address`=
     L'adresse postale du membre.
 =`address`=
     L'adresse postale du membre.

+

 =`email`=
     L'adresse email du membre. C'est à cette adresse que seront envoyés les
     messages de l'assemblée générale et les rappels de cotisation.
 =`email`=
     L'adresse email du membre. C'est à cette adresse que seront envoyés les
     messages de l'assemblée générale et les rappels de cotisation.

+

 =`joined_on`=
     Date d'adhésion à l'association.
 =`joined_on`=
     Date d'adhésion à l'association.

+

 =`membership_fee_paid_on`=
     Date du paiement de la dernière cotisation.
 
 =`membership_fee_paid_on`=
     Date du paiement de la dernière cotisation.
 


@@ -66,7 +69,7 @@ fonctionalités respectives en lisant les cas d'utilisation dans les fichiers
 
 Le chemin vers la racine du clone du wiki du conseil d'amnisitration est
 spécifié par la variable d'environnement `NOS_OIGNONS_BOARD_WIKI_PATH`. Si
 
 Le chemin vers la racine du clone du wiki du conseil d'amnisitration est
 spécifié par la variable d'environnement `NOS_OIGNONS_BOARD_WIKI_PATH`. Si

-cette dernière n'est pas spécifié, les scripts cherchent un répertoire
+cette dernière n'est pas spécifiée, les scripts cherchent un répertoire

 `Membres` à la racine du Git courant, et si ce n'est pas le cas, dans
 le répertoire `wiki-ca` du répertoire parent du Git courant.
 
 `Membres` à la racine du Git courant, et si ce n'est pas le cas, dans
 le répertoire `wiki-ca` du répertoire parent du Git courant.
 


@@ -87,7 +90,7 @@ C.A. (en faisant un lien symbolique dans `.git/hooks/pre-commit`).
 `pre-receive-hook`
 ------------------
 
 `pre-receive-hook`
 ------------------
 

-`pre-commit` hook pour Git. Ce dernier est là pour éviter de pouvoir enregistrer
+`pre-receive` hook pour Git. Ce dernier est là pour éviter de pouvoir enregistrer

 des informations invalides dans la base des membres. Il doit être configuré dans
 le dépôt central du wiki du C.A. (via un lien symbolique dans
 `.git/hooks/pre-receive`).
 des informations invalides dans la base des membres. Il doit être configuré dans
 le dépôt central du wiki du C.A. (via un lien symbolique dans
 `.git/hooks/pre-receive`).


@@ -95,46 +98,79 @@ le dépôt central du wiki du C.A. (via un lien symbolique dans
 `update-ag-subscribers`
 -----------------------
 
 `update-ag-subscribers`
 -----------------------
 

-Met à jour la liste des emails inscrites à la liste ag@ par rapport aux membres
-à jour de cotisation. À exécuter à travers un *cron*. A besoin de pouvoir
-lancer les commandes `list_members`, `add_members` et `remove_members` via
-`sudo` sur le compte `list`.
+Met à jour la liste des adresses email inscrites à la liste *ag@* par rapport
+aux membres à jour de cotisation. À exécuter à travers un *cron*. A besoin de
+pouvoir se connecter à l’API REST de Mailman 3.
+
+La variable d’environnement suivante doit être
+définie `NOS_OIGNONS_MAILMAN_REST_API_URL` avec par exemple :
+`https://user:password@mailman.example.org`
+
+À défaut, cette dernière sera lue depuis le fichier `mailman-rest-url`
+dans le dossier indiqué par la variable d’environnemnet `CREDENTIALS_DIRECTORY`
+(voir [System and Service Credentials](https://systemd.io/CREDENTIALS/) et
+la procédure de déploiement indiqué plus bas).

 
 `send-membership-reminders`
 ---------------------------
 
 
 `send-membership-reminders`
 ---------------------------
 

-Préviens les membres qu'il faut renouveller leur cotisation.
+Préviens les membres qu'il faut renouveler leur cotisation.
+
+Le fichier utilisé pour garder la liste des envois déjà effectués est soit
+celui indiqué par la variable d'environnement `NOS_OIGNONS_REMINDER_DB`, soit
+le fichier `var/reminders.yaml` si la variable est vide.
+
+`send-member-emails-to-advisors`
+--------------------------------
+
+Envoie la liste des emails des membres à jour de cotisation au comité
+de déontologie.
+
+Ce script a vocation a être executé tous les mois afin que le comité
+puisse convoquer une assemblée générale extraordinaire, même en cas de
+défaillance du conseil d'administration.

 
 

-Le fichier utiliser pour garder la liste des envois déjà effectués est soit
-celui indiqué par la variable d'environnement `NOS_OIGNONS_REMINDER_DB`, ou
-le fichier si elle est vide `var/reminders.yaml`.
+`create-membership-fee-receipt`
+-------------------------------
+
+Permet de créer un reçu de cotisation pour les membres en faisant
+la demande.
+
+Exemple d'utilisation :
+
+    bin/create-membership-fee-receipt 000042 10,00
+
+Cela crééra un reçu pour le membre 000042 pour une cotisation d'un montant
+de 10,00€. Le reçu est généré sous forme d'un fichier PDF dans le répertoire
+spécifié par la variable d'environnement NOS_OIGNONS_RECEIPTS_DIR (ou le
+répertoire `receipts` dans le répertoire courant).
+
+**Il faut créer le répertoire avant utilisation s'il n'existe pas déjà.**

 
 Développement
 =============
 
 
 Développement
 =============
 

-L'essentiel du code est en Ruby. Les dépendences sont gérés avec Bundler. Les
-tests d'intégrations sont fait avec Cucumber.
+L'essentiel du code est en Ruby. Les dépendances sont gérées avec Bundler. Les
+tests d'intégrations sont faits avec Cucumber.

 
 

-Installer les paquets Debian qui vont bien (sur Wheezy) :
+Installer les paquets Debian qui vont bien (sur Jessie) :

 
 

-    apt-get install ruby1.9.1 bundler
+    apt-get install bundler

 
 

-Pour récupérer les dépendences :
+Pour récupérer les dépendances :

 
 

-    ruby1.9.1 /usr/bin/bundle install --path=vendor/bundle
+    bundle install --path=vendor/bundle

 
 Déploiement
 ===========
 
 Installer les paquets Debian qui vont bien (sur Wheezy) :
 
 
 Déploiement
 ===========
 
 Installer les paquets Debian qui vont bien (sur Wheezy) :
 

-    apt-get install ruby1.9.1 bundler
+    apt-get install bundler

 
 

-Installer les dépendences :
+Installer les dépendances :

 
 

-    ruby1.9.1 /usr/bin/bundle install --deployment \
-                                      --without=development \
-                                      --path=vendor/bundle
+    bundle install --deployment --without=development --path=vendor/bundle

     chmod -R o+rX vendor/bundle
 
 Il faut donner les droits d'écriture à `wiki-ca` sur le répertoire `var`.
     chmod -R o+rX vendor/bundle
 
 Il faut donner les droits d'écriture à `wiki-ca` sur le répertoire `var`.


@@ -148,28 +184,106 @@ Pour rendre facilement accessible `list-members-emails`, on peut ajouter dans
 
 Ne pas oublier de le rendre exécutable.
 
 
 Ne pas oublier de le rendre exécutable.
 

-Pour permettre au script `update-ag-subscribers` de fonctionner, il est
-nécessaire de l'autoriser à exécuter certaines commandes de Mailman.
-Pour cela, on va créer un fichier dans `/etc/sudoers.d` :
+On va utiliser des
+[services](https://www.freedesktop.org/software/systemd/man/systemd.service.html)
+et des [timers](https://www.freedesktop.org/software/systemd/man/systemd.timer.html)
+systemd pour les scripts à utiliser régulièrement.
+
+Dans `/etc/systemd/system/gestion-adh-update-ag-subscribers.service` :
+
+    [Unit]
+    Description=Update subscribers of the `ag` mailing list according to memberships
+
+    [Service]
+    Type=oneshot
+    WorkingDirectory=/srv/ikiwiki/wiki-ca/gestion-adh
+    User=wiki-ca
+    ExecStart=/srv/ikiwiki/wiki-ca/gestion-adh/bin/update-ag-subscribers
+    Environment=BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile NOS_OIGNONS_BOARD_WIKI_PATH=/srv/ikiwiki/wiki-ca/src
+    SyslogIdentifier=update-ag-subscribers
+    ProtectSystem=strict
+    ProtectHome=true
+    PrivateTmp=yes
+    PrivateDevices=yes

 
 

-    Defaults:wiki-ca !requiretty
+Dans `/etc/systemd/system/gestion-adh-update-ag-subscribers.timer` :

 
 

-    Cmnd_Alias AG_MANAGEMENT = /usr/sbin/list_members ag,\
-                               /usr/sbin/add_members -r - ag,\
-                               /usr/sbin/remove_members -f - ag
+    [Unit]
+    Description=Run update-ag-subscribers every hour

 
 

-    wiki-ca ALL = (list) NOPASSWD: AG_MANAGEMENT
+    [Timer]
+    RandomizedDelaySec=30min
+    OnCalendar=hourly

 
 

-Ensuite, pour exécuter régulièrement les scripts via le *crontab* du compte
-`wiki-ca`, il faut y ajouter :
+    [Install]
+    WantedBy=timers.target

 
 

-    42 * * * * BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile NOS_OIGNONS_BOARD_WIKI_PATH=/srv/ikiwiki/wiki-ca/src ruby1.9.1 /srv/ikiwiki/wiki-ca/gestion-adh/bin/update-ag-subscribers
-    42 6 * * * BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile NOS_OIGNONS_BOARD_WIKI_PATH=/srv/ikiwiki/wiki-ca/src ruby1.9.1 /srv/ikiwiki/wiki-ca/gestion-adh/bin/send-membership-reminders
+Il est également nécessaire de configurer le *credential* avec les informations
+de connexion à Mailman :
+
+    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
+
+Dans `/etc/systemd/system/gestion-adh-send-membership-reminders.service` :
+
+    [Unit]
+    Description=Send reminders to renew membership
+
+    [Service]
+    Type=oneshot
+    WorkingDirectory=/srv/ikiwiki/wiki-ca/gestion-adh
+    User=wiki-ca
+    ExecStart=/srv/ikiwiki/wiki-ca/gestion-adh/bin/send-membership-reminders
+    Environment=BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile NOS_OIGNONS_BOARD_WIKI_PATH=/srv/ikiwiki/wiki-ca/src
+    SyslogIdentifier=send-membership-reminders
+    ProtectSystem=strict
+    ProtectHome=true
+    PrivateTmp=yes
+    PrivateDevices=yes
+    ReadWritePaths=/srv/ikiwiki/wiki-ca/gestion-adh/var
+
+Dans `/etc/systemd/system/gestion-adh-send-membership-reminders.timer` :
+
+    [Unit]
+    Description=Run send-membership-reminders every day
+
+    [Timer]
+    OnCalendar=06:42
+
+    [Install]
+    WantedBy=timers.target
+
+Dans `/etc/systemd/system/gestion-adh-send-member-emails-to-advisors.service` :
+
+    [Unit]
+    Description=Send member emails to the advisory board
+
+    [Service]
+    Type=oneshot
+    WorkingDirectory=/srv/ikiwiki/wiki-ca/gestion-adh
+    User=wiki-ca
+    ExecStart=/srv/ikiwiki/wiki-ca/gestion-adh/bin/send-member-emails-to-advisors
+    Environment=BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile NOS_OIGNONS_BOARD_WIKI_PATH=/srv/ikiwiki/wiki-ca/src
+    SyslogIdentifier=send-member-emails-to-advisors
+    ProtectSystem=strict
+    ProtectHome=true
+    PrivateTmp=yes
+    PrivateDevices=yes
+
+Dans `/etc/systemd/system/gestion-adh-send-member-emails-to-advisors.timer` :
+
+    [Unit]
+    Description=Run send-member-emails-to-advisors monthly
+
+    [Timer]
+    OnCalendar=monthly
+
+    [Install]
+    WantedBy=timers.target

 
 Pour installer le `pre-commit` *hook* sur le dépôt utilisé par
 Ikiwiki, on met dans `/srv/ikiwiki/wiki-ca/src/.git/hooks/pre-commit` :
 
 
 Pour installer le `pre-commit` *hook* sur le dépôt utilisé par
 Ikiwiki, on met dans `/srv/ikiwiki/wiki-ca/src/.git/hooks/pre-commit` :
 

-    if ! BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile ruby1.9.1 /srv/ikiwiki/wiki-ca/gestion-adh/bin/pre-commit-hook; then
+    if ! BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile /srv/ikiwiki/wiki-ca/gestion-adh/bin/pre-commit-hook; then

             # Reset changes that do not pass the pre-commit hook to prevent
             # wrong changes to lay in the Ikiwiki source directory.
             git reset --hard
             # Reset changes that do not pass the pre-commit hook to prevent
             # wrong changes to lay in the Ikiwiki source directory.
             git reset --hard


@@ -182,8 +296,23 @@ Pour installer le `pre-receive` *hook* sur le dépôt central, on met dans
 `/srv/git/.gitolite/hooks/wiki-ca/hooks/pre-receive` :
 
     #!/bin/sh
 `/srv/git/.gitolite/hooks/wiki-ca/hooks/pre-receive` :
 
     #!/bin/sh

-    BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile ruby1.9.1 /srv/ikiwiki/wiki-ca/gestion-adh/bin/pre-receive-hook
+    BUNDLE_GEMFILE=/srv/ikiwiki/wiki-ca/gestion-adh/Gemfile /srv/ikiwiki/wiki-ca/gestion-adh/bin/pre-receive-hook

 
 Ne pas oublier de le rendre exécutable. Il faut ensuite faire un lien symbolique :
 
     ln -s ../../../.gitolite/hooks/wiki-ca/pre-receive /srv/git/repositories/wiki-ca.git/hooks/pre-receive
 
 Ne pas oublier de le rendre exécutable. Il faut ensuite faire un lien symbolique :
 
     ln -s ../../../.gitolite/hooks/wiki-ca/pre-receive /srv/git/repositories/wiki-ca.git/hooks/pre-receive

+
+Licences
+========
+
+Système de gestion des adhésions de Nos oignons  
+Copyright © 2013-2014 Nos oignons <contact@nos-oignons.net>  
+Licence : GNU AGPLv3 ou ultérieur, voir `LICENCE`
+
+Police OpenSans  
+Copyright © 2010-2011, Google Corporation  
+Licence : Apache 2.0, voir `share/fonts/OpenSans/Apache-2.0`
+
+Logo Nos oignons  
+Copyright © 2013 lutopiquant  
+Licence : CC BY-SA 3.0 FR, voir <https://creativecommons.org/licenses/by-sa/3.0/fr/deed.fr>