Doc

README.md

@@ -22,13 +22,13 @@ bundle install
 
 Créer un fichier `.env` à la racine du projet :
 
-```sh
+```dotenv
 RACK_ENV=development
 SESSION_SECRET=...
 RODAUTH_HMAC_SECRET=...
 RODAUTH_DOMAIN=netig.net
 BASE_URL=http://[::1]:9292
-SMTP_PASSWORD=...
+SMTP_PASSWORD='...'
 ```
 
 Générer `SESSION_SECRET` et `RODAUTH_HMAC_SECRET` avec :
@@ -37,21 +37,13 @@ Générer `SESSION_SECRET` et `RODAUTH_HMAC_SECRET` avec :
 openssl rand -hex 64
 ```
 
-Utiliser une valeur différente pour chaque secret.
+Utiliser une valeur différente pour chaque secret. Les valeurs contenant
+`#`, des espaces ou des caractères interprétés spécialement peuvent être
+entourées d'apostrophes simples.
 
-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.
+Le fichier `.env` est chargé automatiquement en développement par
+`config/boot.rb`. Ce fichier est chargé par `netig.rb` et directement
+par les scripts de `bin/` qui ont besoin de la configuration.
 
 Ne pas versionner le fichier `.env`.
 
@@ -63,9 +55,9 @@ En développement, la base est créée par défaut dans :
 db/development.sqlite3
 ```
 
-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.
+Ce chemin peut être remplacé par la variable d'environnement
+`DATABASE_PATH`. Un chemin relatif est résolu à partir du répertoire
+de `lib/database.rb`, et non du répertoire courant.
 
 Créer ou mettre à jour la base de données :
 
@@ -75,13 +67,13 @@ bundle exec ruby bin/migrate
 
 ### Serveur
 
-Démarrer le serveur depuis la racine du projet :
+Démarrer le serveur de développement depuis la racine du projet :
 
 ```sh
 bundle exec puma
 ```
 
-Puma charge automatiquement `config.ru`.
+Puma charge automatiquement `config.ru`, qui démarre l'application.
 
 Ouvrir la page de création de compte :
 
@@ -102,33 +94,38 @@ bundle exec ruby bin/add-core-member adresse@example.net
 ```
 
 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`.
+la fiche membre doit correspondre à une personne physique. Une adhésion
+au statut `accepted` doit également déjà exister dans `memberships`.
 
-Le script ne crée ni le compte ni l'adhésion : il attribue uniquement
+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.
+La gestion des demandes d'adhésion n'est pas encore disponible dans
+l'interface. Une adhésion acceptée doit donc être enregistrée dans la
+base avant l'utilisation de ce script.
+
+Les statuts prévoient un Noyau composé d'au moins trois personnes
+physiques.
 
 ### Shell interactif
 
-Après avoir chargé les variables d'environnement dans le terminal,
-ouvrir un shell interactif avec l'application chargée :
+Ouvrir un shell interactif avec l'application chargée :
 
 ```sh
 bundle exec irb -r ./netig.rb
 ```
 
+`netig.rb` charge également `config/boot.rb` : les variables du fichier
+`.env` sont donc disponibles en développement.
+
 ## 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` :
+par Docker Compose. Le service doit définir `RACK_ENV=production` et
+transmettre le fichier d'environnement avec `env_file`.
+
+Exemple de configuration :
 
 ```yaml
 services:
@@ -139,16 +136,18 @@ services:
       RACK_ENV: production
 ```
 
-Sur le serveur, le fichier `.env` doit notamment contenir :
+La variable définie dans `environment` prend le dessus sur une éventuelle
+valeur de `RACK_ENV` présente dans `.env`.
 
-```sh
-RACK_ENV=production
+Le fichier `.env` de production doit notamment contenir :
+
+```dotenv
 DATABASE_PATH=../db/netig.sqlite3
 SESSION_SECRET=...
 RODAUTH_HMAC_SECRET=...
 RODAUTH_DOMAIN=netig.net
 BASE_URL=https://netig.net
-SMTP_PASSWORD=...
+SMTP_PASSWORD='...'
 ```
 
 Générer `SESSION_SECRET` et `RODAUTH_HMAC_SECRET` avec :
@@ -157,8 +156,8 @@ Générer `SESSION_SECRET` et `RODAUTH_HMAC_SECRET` avec :
 openssl rand -hex 64
 ```
 
-Utiliser une valeur différente pour chaque secret et ne pas versionner
-le fichier contenant ces variables.
+Utiliser des secrets propres à la production et ne pas versionner le
+fichier contenant ces variables.
 
 ### Base de données
 
@@ -168,7 +167,7 @@ La base de production est stockée dans :
 db/netig.sqlite3
 ```
 
-Le chemin `../db/netig.sqlite3` est relatif au fichier
+Le chemin `../db/netig.sqlite3` est relatif au répertoire de
 `lib/database.rb`. Il désigne donc le dossier `db/` à la racine du
 projet, dans le conteneur.
 
@@ -176,9 +175,9 @@ 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 et le même stockage persistant
-que l'application, avant de démarrer la nouvelle version :
+Créer ou mettre à jour la base dans le conteneur applicatif, avec les
+mêmes variables d'environnement et le même stockage persistant que
+l'application, avant de démarrer la nouvelle version :
 
 ```sh
 docker compose run --rm netig bundle exec ruby bin/migrate
@@ -188,8 +187,8 @@ Cette commande suppose que le service Compose s'appelle `netig`.
 
 ### Initialisation du premier Noyau
 
-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
+Chaque personne désignée pour siéger au Noyau doit d'abord créer un
+compte depuis le site et vérifier son adresse électronique. Sa fiche
 membre doit également disposer d'une adhésion au statut `accepted`.
 
 Pour chaque personne, exécuter dans le conteneur applicatif :
@@ -203,4 +202,5 @@ 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.
 
-Les statuts prévoient au moins trois personnes physiques au Noyau.
+Les statuts prévoient un Noyau composé d'au moins trois personnes
+physiques.