Document maillists module

README.md

@@ -323,6 +323,10 @@ Some apps are not enabled by default :
    any authentication backend or user configuration ("marque blanche")
 - *hardware_provisioning* : Self-service app to manage hardware inventory,
   hardware lent to members or in different stock sites.
+- *maillists* : Self-service mailling-list (un)subscription for members:
+  handles subscribers list for a third-party mailling-list server (sympa,
+  mailman…
+  etc). See [maillists app documentation (fr)](doc/admin/maillists.md).
 
 You can enable them using the `EXTRA_INSTALLED_APPS` setting.
 E.g. in `settings_local.py`:

doc/admin/maillists.md

@@ -0,0 +1,118 @@
+<style>
+figure img {
+    max-width: 30rem;
+}
+</style>
+
+Gestion des abonnements aux listes mail
+=======================================
+
+Coin offre un module optionnel pour que les adhérent·e·s puissent
+s'abonner/désabonner aux listes mail de l'asso. de manière autonome (listes de
+discussions et/ou de diffusion).
+
+Coin n'est pas lui-même un serveur de listes mail. Il se contente de
+s'interfacer avec ce dernier pour lui pousser des liste d'inscrit·e·s.
+
+Il existe une interface membre pour auto-gérer ses propres abonnements, et une
+interface admin pour gérer l'ensemble des abonnements lorsqu'on possède les
+droits admin dans coin.
+
+
+<figure>
+![vue adhérent](../_img/user-maillists.png)
+![vue admin](../_img/admin-maillists.png)
+<figcaption>Vues adhérent·e et admin</figcaption>
+</figure>
+
+
+
+Fonctionnement
+--------------
+
+Coin stocke les abonnements des membres aux listes dans sa base de données, en
+utilisant l'adresse mail de la fiche membre.
+
+Il synchronise ensuite ces listes vers le serveur de listes mail en appelant
+une commande pour chaque liste gérée. Cette commande est configurable, et
+reçoit sur son entrée standard la liste des emails inscrits (une adresse mail
+par ligne).
+
+Si le serveur de base données est sur une machine différente du serveur Coin,
+il est possible d'utiliser la commande SSH qui appelle un script distant.
+
+
+La synchronisation sera faite :
+
+- À l'abonnement/désabonnement à une liste via l'interface admin de Coin
+  (section « Listes mail ») ;
+- à l'abonnement/désabonnement à une liste via l'interface membre de Coin ;
+- au changement d'adresse mail d'un·e adhérent·e ;
+- à la suppression d'un·e adhérent·e.
+
+Avertissements
+---------------
+
+- En l'état, tout membre avec des identifiants Coin aura pouvoir d'auto-gérer
+son inscription à toute liste gérée par coin. Il n'est cependant pas
+obligatoire donner à Coin la main sur les abonnements à toutes les listes d'un
+serveur de listes.
+
+- Il est préférable que les listes mail gérées par Coin le soient totalement. Si
+des inscriptions sont faites par d'autres moyens (mail, interface du serveur de
+liste de discussions… etc), ces modifications risquent d'être écrasées par la
+gestion d'abonnements de Coin.
+
+
+
+Mise en place
+-------------
+
+
+### 1. Activer l'app *maillist*
+
+Il faut activer l'app *maillists*, cela
+fonctionne
+[comme les autres apps optionelles](../README.md#using-optional-apps). Il faut
+ensuite lancer la commande suivante pour mettre à jour la base de données :
+
+    ./manage.py migrate
+
+
+### 2. Configurer la synchronisation.
+
+
+Il y a un paramètre obligatoire à renseigner dans votre fichier.
+*settings_local.py* : `MAILLIST_SYNC_COMMAND`.
+
+Il s'agit de la commande à lancer pour « pousser » la liste d'emails inscrits à
+une liste mail donnée. 
+
+Vous pouvez utiliser des variables dans la commande à
+lancer :
+
+- `{short_name}` : l'identifiant court de la liste (ex: *discussion*)
+- `{email}` : l'email de la liste (ex: *discussion@example.com*)
+
+Si par exemple votre serveur de listes attend un bête fichier texte
+avec une adresse par ligne dans */etc/lists/nomdelaliste* :
+
+
+    MAILLIST_SYNC_COMMAND = 'cat /etc/lists/{short_name}'
+    
+Si le ce même serveur se situe sur un autre serveur, on pourra utiliser par
+exemple :
+
+    MAILLIST_SYNC_COMMAND = "ssh coin@mail.example.com 'cat /etc/lists/{short_name}'"
+
+Des cas d'usages plus complexes (ex: inscription via une API HTTP) sont
+envisageables en recourant à un petit script sur mesure.
+
+
+### 3. Ajouter des listes
+
+
+Se rendre dans l'admin de coin et dans la nouvelle catégorie « Listes mail »,
+renseigner les listes mail que l'on souhaite voir gérées par Coin.
+
+