From 06312e8d83f94939abfe353ea9f027f7b1c6c81a Mon Sep 17 00:00:00 2001 From: julien Date: Tue, 3 Nov 2026 17:50:16 +0100 Subject: [PATCH] Doc --- Gemfile | 1 - Gemfile.lock | 3 - README.md | 143 +++++++++++++++++++++++++++++--------------- bin/add-core-member | 2 - bin/migrate | 1 - config.ru | 1 - 6 files changed, 94 insertions(+), 57 deletions(-) diff --git a/Gemfile b/Gemfile index ccb4d01..3405056 100644 --- a/Gemfile +++ b/Gemfile @@ -5,7 +5,6 @@ source "https://rubygems.org" # Development group :development do gem "irb" - gem "dotenv" end # Base diff --git a/Gemfile.lock b/Gemfile.lock index e31afc5..29782aa 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -5,7 +5,6 @@ GEM bigdecimal (4.1.3) commonmarker (2.10.1-x86_64-linux) date (3.6.0) - dotenv (3.2.0) erb (6.0.7) erubi (1.13.1) io-console (0.9.4) @@ -68,7 +67,6 @@ PLATFORMS DEPENDENCIES bcrypt commonmarker - dotenv erubi irb mail @@ -84,7 +82,6 @@ CHECKSUMS bigdecimal (4.1.3) sha256=61ebe1e5e559bdc3cc6f2c0ee7f427321fc838f59611c294356eb04d6e21cf66 commonmarker (2.10.1-x86_64-linux) sha256=4b2c4b9084baca131146c92dde02bcb40ef3d2768a6772648c1970bb51842734 date (3.6.0) sha256=18ac945c4e24ebd93534f8eab8c2fd8c5604b3e977105b3798d62a1e8d27b580 - dotenv (3.2.0) sha256=e375b83121ea7ca4ce20f214740076129ab8514cd81378161f11c03853fe619d erb (6.0.7) sha256=c5ca6dc25b0ef974a44dc8f59fe847577122483b1968a38dec305c60bf91ee92 erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9 io-console (0.9.4) sha256=a403304f32928ee85e56d457b4612ca43f2703b561a3258844992bd24085fbb1 diff --git a/README.md b/README.md index b470137..c8beb7d 100644 --- a/README.md +++ b/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. diff --git a/bin/add-core-member b/bin/add-core-member index b6f975e..6b5b69c 100644 --- a/bin/add-core-member +++ b/bin/add-core-member @@ -1,7 +1,5 @@ #!/usr/bin/env ruby -require "dotenv/load" if ENV.fetch("RACK_ENV", "development") == "development" - require_relative "../lib/database" abort "Usage: ruby bin/add-core-member EMAIL" unless ARGV.one? diff --git a/bin/migrate b/bin/migrate index b8bfd9f..0add3e9 100644 --- a/bin/migrate +++ b/bin/migrate @@ -1,6 +1,5 @@ #!/usr/bin/env ruby -require "dotenv/load" if ENV.fetch("RACK_ENV", "development") == "development" require_relative "../lib/database" Sequel.extension :migration diff --git a/config.ru b/config.ru index 8f4780a..f43bec0 100644 --- a/config.ru +++ b/config.ru @@ -1,4 +1,3 @@ -require "dotenv/load" if ENV.fetch("RACK_ENV", "development") == "development" require_relative "netig" run Netig.freeze.app