====================================
Gestion des adhésions de Nos oignons
====================================

Voici une collection de scripts et de bouts de code qui permettent de gérer les
adhésions de Nos oignons conformément aux statuts de l'association.

Base des membres
================

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 :

    Membres
    ├── 000000.mdwn
    ├── 000001.mdwn
    ├── 000002.mdwn
    ├── 000003.mdwn
    ├── 000004.mdwn
    …
    └── 000042.mdwn

Chaque page doit ressembler à :

    ---
    name: Violette Dupuis
    address: |
      42 rue du Fleuve
      12042 Essaiville
    email: violette@example.org
    joined_on: 2013-05-25
    membership_fee_paid_on: 2013-05-25
    ---

    Violette sait programmer en Ruby, on peut lui demander si on a besoin de
    coup de main.

Le début de chaque page est un morceau de [YAML]. Il doit contenir les entrées
suivantes :

=`name`=
    Le nom (complet) 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.

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

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

Le reste de la page peut servir à noter ce qu'on veut.

[YAML]: http://yaml.org/

Scripts
=======

Voici le détail des scripts utilisés. On peut se faire une idée de leurs
fonctionalités respectives en lisant les cas d'utilisation dans les fichiers
`features/*.feature`.

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é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.

`list-email`
------------

Affiche sur la sortie standard les adresses emails des membres à jour de
cotisation.

`pre-commit-hook`
-----------------

`pre-commit` hook pour Git. Ce dernier est avant tout là pour éviter de pouvoir
enregistrer des informations invalides dans la base des membres depuis Ikiwiki.
Il est nécessaire de le configurer à chaque fois qu'on clone le dépôt du wiki du
C.A. (en faisant un lien symbolique dans `.git/hooks/pre-commit`).

`pre-receive-hook`
------------------

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

`update-ag-subscribers`
-----------------------

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

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.

`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
=============

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 Jessie) :

    apt-get install bundler

Pour récupérer les dépendances :

    bundle install --path=vendor/bundle

Déploiement
===========

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

    apt-get install bundler

Installer les dépendances :

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

Pour rendre facilement accessible `list-members-emails`, on peut ajouter dans
`/usr/local/bin` un mini script tel que celui-ci :

    #!/bin/sh
    NOS_OIGNONS_BOARD_WIKI_PATH=/srv/ikiwiki/wiki-ca/src \
        /srv/ikiwiki/wiki-ca/gestion-adh/bin/list-emails

Ne pas oublier de le rendre exécutable.

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

Dans `/etc/systemd/system/gestion-adh-update-ag-subscribers.timer` :

    [Unit]
    Description=Run update-ag-subscribers every hour

    [Timer]
    RandomizedDelaySec=30min
    OnCalendar=hourly

    [Install]
    WantedBy=timers.target

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` :

    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
            exit 1
    fi

Ne pas oublier de le rendre exécutable.

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

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>
