Doc

README.md

@@ -2,23 +2,28 @@
 
 ## À faire
 
-- limiter le spam sur `/contact/send`
-- développer les demandes d'adhésion et leur examen par le Noyau
-- développer l'espace personnel des membres
-- afficher les recettes et les dépenses sur la page d'accueil
-- gérer les accès aux services selon la situation des membres
+- limiter le spam sur `/contact/send` ;
+- développer les demandes d'adhésion et leur examen par le Noyau ;
+- développer l'espace personnel des membres ;
+- afficher les recettes et les dépenses sur la page d'accueil ;
+- gérer les accès aux services selon la situation des membres.
 
 ## Développement
 
+### Dépendances
+
 Installer les dépendances :
 
 ```sh
 bundle install
 ```
 
+### Variables d'environnement
+
 Créer un fichier `.env` à la racine du projet :
 
-```dotenv
+```sh
+RACK_ENV=development
 SESSION_SECRET=...
 RODAUTH_HMAC_SECRET=...
 RODAUTH_DOMAIN=netig.net
@@ -32,20 +37,35 @@ Générer `SESSION_SECRET` et `RODAUTH_HMAC_SECRET` avec :
 openssl rand -hex 64
 ```
 
+Utiliser une valeur différente pour chaque secret.
+
+Le projet ne charge pas lui-même le fichier `.env`. Pour rendre ses
+variables disponibles dans le terminal courant :
+
+```sh
+set -a
+. ./.env
+set +a
+```
+
+Exécuter ces commandes depuis la racine du projet, dans chaque nouveau
+terminal utilisé pour le développement. Le fichier doit respecter la
+syntaxe du shell ; mettre entre quotes les valeurs qui contiennent des
+caractères interprétés par celui-ci.
+
 Ne pas versionner le fichier `.env`.
 
 ### Base de données
 
-En développement, la base est créée dans :
+En développement, la base est créée par défaut dans :
 
 ```text
 db/development.sqlite3
 ```
 
-Ce chemin est utilisé par défaut. Il est possible de le modifier
-avec la variable d'environnement `DATABASE_PATH`.
-
-Le chemin indiqué est relatif au fichier `lib/database.rb`.
+Ce chemin est défini dans `lib/database.rb`. Il peut être modifié avec
+la variable d'environnement `DATABASE_PATH`. Un chemin relatif est
+résolu à partir du répertoire `lib/`, et non du répertoire courant.
 
 Créer ou mettre à jour la base de données :
 
@@ -55,48 +75,74 @@ bundle exec ruby bin/migrate
 
 ### Serveur
 
-Démarrer le serveur de développement :
+Démarrer le serveur depuis la racine du projet :
 
 ```sh
 bundle exec puma
 ```
 
-Créer des comptes de test depuis le site :
+Puma charge automatiquement `config.ru`.
 
+Ouvrir la page de création de compte :
+
+```text
 http://[::1]:9292/create-account
+```
 
 Les personnes physiques et les personnes morales peuvent créer un compte.
-L'adresse électronique doit être vérifiée avant de pouvoir se connecter.
+La création du compte crée également une fiche dans `members`. L'adresse
+électronique doit être vérifiée avant de pouvoir se connecter.
 
 ### Initialisation du Noyau
 
-Pour tester l'espace du Noyau, ajouter un compte de test depuis le terminal :
+Pour ajouter une personne au Noyau, utiliser le script :
 
 ```sh
-bundle exec ruby bin/initialize-core
+bundle exec ruby bin/add-core-member adresse@example.net
 ```
 
-En développement, un seul membre suffit. Cette commande peut être
-réexécutée pour ajouter d'autres membres au Noyau.
+Le compte doit exister, son adresse électronique doit être vérifiée et
+il doit s'agir d'une personne physique. Une adhésion avec le statut
+`accepted` doit également déjà exister dans `memberships`.
 
-Chaque exécution ajoute un seul membre.
+Le script ne crée ni le compte ni l'adhésion : il attribue uniquement
+la qualité de membre du Noyau à une fiche membre qui remplit ces
+conditions. Il doit être exécuté séparément pour chaque personne.
+
+Le traitement des demandes d'adhésion n'étant pas encore développé,
+la procédure qui permet d'obtenir une adhésion acceptée reste à mettre
+en place. Les statuts prévoient un Noyau composé d'au moins trois
+personnes physiques.
 
 ### Shell interactif
 
-Pour ouvrir un shell interactif :
+Après avoir chargé les variables d'environnement dans le terminal,
+ouvrir un shell interactif avec l'application chargée :
 
 ```sh
-bundle exec irb -r dotenv/load -r ./netig.rb
+bundle exec irb -r ./netig.rb
 ```
 
 ## Production
 
-Docker Compose fournit les variables d'environnement via `env_file`
-et définit `RACK_ENV=production`.
+En production, les variables d'environnement sont fournies au conteneur
+par Docker. Le service Docker Compose doit notamment définir
+`RACK_ENV=production` et transmettre le fichier d'environnement avec
+`env_file` :
 
-Le fichier d'environnement doit notamment définir :
+```yaml
+services:
+  netig:
+    env_file:
+      - .env
+    environment:
+      RACK_ENV: production
+```
 
-```dotenv
+Sur le serveur, le fichier `.env` doit notamment contenir :
+
+```sh
+RACK_ENV=production
 DATABASE_PATH=../db/netig.sqlite3
 SESSION_SECRET=...
 RODAUTH_HMAC_SECRET=...
@@ -105,13 +151,14 @@ BASE_URL=https://netig.net
 SMTP_PASSWORD=...
 ```
 
-Générer les deux secrets avec :
+Générer `SESSION_SECRET` et `RODAUTH_HMAC_SECRET` avec :
 
 ```sh
 openssl rand -hex 64
 ```
 
-Ne pas versionner le fichier contenant ces variables.
+Utiliser une valeur différente pour chaque secret et ne pas versionner
+le fichier contenant ces variables.
 
 ### Base de données
 
@@ -122,40 +169,38 @@ db/netig.sqlite3
 ```
 
 Le chemin `../db/netig.sqlite3` est relatif au fichier
-`lib/database.rb`. Il désigne donc le dossier `db/` à la racine
-du projet.
+`lib/database.rb`. Il désigne donc le dossier `db/` à la racine du
+projet, dans le conteneur.
 
-Le dossier `db/` doit être conservé entre les déploiements et rester
-accessible en écriture par l'utilisateur qui exécute Puma.
-
-Il doit également être inclus dans les sauvegardes.
+Le dossier `db/` doit être conservé entre les déploiements, monté sur
+un stockage persistant et accessible en écriture par l'utilisateur
+qui exécute Puma. Il doit également être inclus dans les sauvegardes.
 
 Créer ou mettre à jour la base de données dans le conteneur applicatif,
-avec les mêmes variables d'environnement que l'application, avant
-de démarrer la nouvelle version :
+avec les mêmes variables d'environnement et le même stockage persistant
+que l'application, avant de démarrer la nouvelle version :
 
 ```sh
-bundle exec ruby bin/migrate
+docker compose run --rm netig bundle exec ruby bin/migrate
 ```
 
+Cette commande suppose que le service Compose s'appelle `netig`.
+
 ### Initialisation du premier Noyau
 
-Une fois l'inscription publique disponible, les personnes désignées
-comme membres fondateurs créent leurs comptes personnels depuis le site
-et vérifient leurs adresses électroniques.
+Les personnes désignées pour siéger au Noyau doivent d'abord créer leur
+compte depuis le site et vérifier leur adresse électronique. Leur fiche
+membre doit également disposer d'une adhésion au statut `accepted`.
 
-Après leur désignation par l'assemblée constitutive, initialiser
-le Noyau depuis le conteneur applicatif :
+Pour chaque personne, exécuter dans le conteneur applicatif :
 
 ```sh
-bundle exec ruby bin/initialize-core
+docker compose run --rm netig \
+  bundle exec ruby bin/add-core-member adresse@example.net
 ```
 
-Exécuter cette commande pour chaque personne désignée.
-Chaque exécution ajoute un seul membre du Noyau.
+Cette commande suppose que le service Compose s'appelle `netig`.
+Elle ne crée pas l'adhésion : elle vérifie qu'elle existe et qu'elle
+est acceptée, puis attribue la qualité de membre du Noyau.
 
-La commande enregistre son adhésion comme acceptée et lui attribue
-la qualité de membre du Noyau.
-
-Le Noyau doit compter au moins trois personnes physiques disposant
-d'un compte vérifié.
+Les statuts prévoient au moins trois personnes physiques au Noyau.