README.md

Cantoche #

Application de gestion des repas collectifs : évènements, repas, recettes, ingrédients et liste de courses regroupée par fournisseur.

Fonctionnalités #

  • Créer des évènements, puis des repas avec une date, un moment (midi/soir) et un nombre de convives.
  • Composer un repas avec des recettes réutilisables.
  • Écrire une recette et ses ingrédients pour 10 personnes, avec une unité fixe par ingrédient.
  • Calculer la liste de courses d'un évènement en mettant les recettes à l'échelle des convives de chaque repas.
  • Regrouper les courses par fournisseur, avec une section « Sans fournisseur ».
  • Imprimer la liste de courses.
  • Interface responsive, sans authentification.

Stack #

  • Rust et Topcoat pour le rendu HTML côté serveur.
  • Toasty + SQLite pour la base de données.
  • htmx pour la navigation sans rechargement et les mises à jour partielles de la liste d'ingrédients (version vendue dans assets/htmx.min.js, licence dans assets/htmx.LICENSE). Sans JavaScript, les liens et les formulaires continuent de fonctionner normalement.
  • Tailwind CSS via Topcoat, sans Node pour le front.
  • OpenTelemetry + OTLP HTTP/protobuf pour les traces et les logs.
  • Playwright pour les tests de bout en bout.

Topcoat et Toasty sont encore expérimentaux. Les versions sont épinglées dans Cargo.toml ; garder Cargo.lock avec le code.

Prérequis #

  • Rust stable récent.
  • Node.js et npm (uniquement pour Playwright).
  • Le CLI Topcoat, nécessaire pour topcoat dev, topcoat fmt, la CI et l'image Docker :
cargo install topcoat-cli --version 0.11.0

Sous NixOS, le binaire Tailwind téléchargé par Topcoat ne peut pas s'exécuter. Le build utilise donc le tailwindcss présent dans le PATH ; lancer les commandes dans un shell nixpkgs :

nix shell nixpkgs#tailwindcss_4

TAILWINDCSS permet de pointer vers un autre binaire Tailwind.

Démarrage #

topcoat dev

Ouvrir http://127.0.0.1:3000. L'application applique les migrations embarquées à chaque démarrage.

La base par défaut est data.db. Pour utiliser un autre fichier :

DATABASE_URL=sqlite:/chemin/vers/cantoche.db topcoat dev

HOST et PORT permettent de changer l'adresse d'écoute, par exemple :

HOST=0.0.0.0 PORT=8080 topcoat dev

Migrations #

Les migrations sont embarquées dans le binaire et appliquées automatiquement au démarrage. Après une modification des modèles Toasty, générer une migration avec le CLI (activé par la fonctionnalité cli) :

cargo run --features cli -- toasty migration generate --name description_du_changement

Les migrations sont dans toasty/ et doivent être versionnées. Pour les appliquer explicitement sans démarrer le serveur :

cargo run --features cli -- toasty migration apply

Tests #

Tests unitaires (calcul des quantités, formatage) :

cargo test

Tests e2e Playwright :

npm install
npx playwright install chromium
npx playwright test

Sous NixOS, le Chromium de Playwright ne démarre pas directement. Les tests acceptent alors le Chromium de nixpkgs via PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH (c'est ce que fait la CI) :

PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH="$(command -v chromium)" npx playwright test

Le lancement des tests démarre toujours une base SQLite neuve dans /tmp/opencode/cantoche-e2e.db (modifiable avec CANTOCHE_E2E_DB) et un serveur sur le port 3101 (reuseExistingServer: false). Les tests sont volontairement exécutés en série (workers: 1).

Formatage et vérifications :

cargo fmt --check
topcoat fmt --check # avec le CLI Topcoat
cargo clippy --all-targets -- -D warnings

L'intégration continue (.tangled/workflows/) exécute cargo fmt --check, topcoat fmt --check, Clippy, les tests unitaires, le build de production et les tests Playwright.

Règles métier #

  • Les recettes sont globales et réutilisables. Modifier une recette met à jour tous les repas qui l'utilisent.
  • Les quantités d'une recette sont pour 10 personnes. Pour un repas de N convives, elles sont multipliées par N / 10.
  • Un repas peut contenir plusieurs plats ; chaque plat est prévu pour tous les convives du repas.
  • L'unité est fixe par ingrédient (kg, L, pièce, botte...). Il n'y a pas de conversion automatique : les lignes d'une même recette utilisent l'unité de l'ingrédient.
  • La liste de courses additionne les quantités de tous les plats de l'évènement, puis groupe par fournisseur.
  • La suppression d'un fournisseur utilisé par un ingrédient, d'un ingrédient utilisé dans une recette ou d'une recette utilisée dans un repas est bloquée.
  • Supprimer un évènement supprime ses repas et ses plats ; supprimer un repas supprime ses plats.

Modèle de données #

fournisseur(id, nom)
ingredient(id, nom, unite, fournisseur_id?)
recette(id, nom, instructions)
recette_ingredient(recette_id, ingredient_id, quantite)  -- pour 10 personnes
evenement(id, nom, date_debut?, date_fin?, convives_defaut)
repas(id, evenement_id, date, moment, convives)
plat(repas_id, recette_id, position)

Structure du projet #

Chemin Contenu
src/app.rs, src/app/ Routes, pages et layouts Topcoat.
src/features/ Modèles Toasty et règles métier.
src/features/courses.rs Agrégation des courses et tests unitaires du calcul.
src/components.rs Composants et styles partagés.
src/db.rs Connexion SQLite et lecture de DATABASE_URL.
src/migrations.rs Migrations Toasty embarquées et appliquées au démarrage.
assets/htmx.min.js htmx servi localement.
toasty/ Migrations et snapshots Toasty.
e2e/ Tests Playwright et script de démarrage du serveur de test.

Déploiement #

Construire le binaire et le bundle d'assets :

topcoat asset bundle --release

Puis lancer le binaire avec la base de production :

DATABASE_URL=sqlite:/var/lib/cantoche/data.db \
HOST=0.0.0.0 \
PORT=3000 \
./target/release/cantoche

Les migrations embarquées sont appliquées automatiquement au premier lancement.

Le bundle d'assets doit correspondre au binaire. Pour une sauvegarde SQLite :

sqlite3 /var/lib/cantoche/data.db ".backup /var/lib/cantoche/backup.db"

Docker #

Construire l'image de production :

docker build -t cantoche .

Lancer l'application avec un volume persistant pour SQLite :

docker run --rm -p 3000:3000 -v cantoche-data:/data cantoche

L'image :

  • est construite en multi-stage (rust:1.99.0-bookworm puis gcr.io/distroless/cc-debian12) ;
  • contient le binaire release (strippé) et le bundle d'assets généré par topcoat asset bundle --release ;
  • applique les migrations Toasty embarquées au démarrage ;
  • tourne sans shell avec l'utilisateur non privilégié 10001:10001 ;
  • expose un healthcheck sur /health via cantoche healthcheck ;
  • écrit la base dans /data/cantoche.db par défaut.

Pour un montage de répertoire hôte, le répertoire doit être accessible en écriture à l'UID 10001 :

mkdir -p ./data
sudo chown 10001:10001 ./data
docker run --rm -p 3000:3000 -v "$PWD/data:/data" cantoche

Pour AppSignal depuis Docker, pointer vers le collecteur accessible depuis le conteneur et garder OTEL_LOGS_EXPORTER=none (le collecteur AppSignal ne supporte pas encore les logs OTel) :

docker run --rm -p 3000:3000 \
  -v cantoche-data:/data \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://host.docker.internal:8099 \
  -e APPSIGNAL_APP_NAME=Cantoche \
  -e APPSIGNAL_ENVIRONMENT=production \
  -e APPSIGNAL_PUSH_API_KEY=... \
  -e APPSIGNAL_REVISION="$(git rev-parse --short HEAD)" \
  -e OTEL_LOGS_EXPORTER=none \
  cantoche

Sous Linux, ajouter --add-host=host.docker.internal:host-gateway si le collecteur tourne sur la machine hôte, ou utiliser le nom du service collecteur dans le réseau Docker.

Observabilité #

L'application écrit toujours ses logs sur stdout. Si OTEL_EXPORTER_OTLP_ENDPOINT est défini, elle exporte aussi des traces et des logs en OTLP HTTP/protobuf.

Sans endpoint OTLP, aucun appel réseau n'est effectué : le développement local et les tests restent silencieux côté export.

Variables d'environnement #

Variable Rôle Défaut
OTEL_EXPORTER_OTLP_ENDPOINT URL de base OTLP HTTP ; aucun export si vide vide
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT URL complète des traces, prioritaire sur la base base + /v1/traces
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT URL complète des logs, prioritaire sur la base base + /v1/logs
OTEL_EXPORTER_OTLP_HEADERS En-têtes HTTP OTLP, lus par l'exporteur vide
OTEL_TRACES_EXPORTER otlp ou none otlp
OTEL_LOGS_EXPORTER otlp ou none otlp
OTEL_SDK_DISABLED true pour désactiver tout export OTLP false
OTEL_SERVICE_NAME Nom du service OTel cantoche
RUST_LOG Filtre des logs stdout info,cantoche=debug
APPSIGNAL_APP_NAME Nom de l'application dans AppSignal Cantoche
APPSIGNAL_ENVIRONMENT Environnement AppSignal APP_ENV ou development
APPSIGNAL_PUSH_API_KEY Clé Push API AppSignal vide
APPSIGNAL_REVISION Révision/déploiement GIT_COMMIT_SHA ou unknown
HOSTNAME Attribut host.name unknown

L'URL est donc configurable par variable d'environnement, sans URL ni secret codés en dur.

AppSignal #

Le collecteur AppSignal écoute par défaut sur le port 8099 et attend de l'OTLP HTTP/protobuf. Exemple :

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:8099 \
APPSIGNAL_APP_NAME=Cantoche \
APPSIGNAL_ENVIRONMENT=production \
APPSIGNAL_PUSH_API_KEY=... \
APPSIGNAL_REVISION="$(git rev-parse --short HEAD)" \
OTEL_LOGS_EXPORTER=none \
./target/release/cantoche

L'application ajoute automatiquement les attributs de ressource AppSignal (appsignal.config.name, appsignal.config.environment, appsignal.config.push_api_key, appsignal.config.revision, appsignal.config.language_integration, appsignal.config.app_path), ainsi que service.name, service.version et host.name.

Limite actuelle : le collecteur AppSignal ne supporte pas encore les logs OTel. Pour AppSignal, garder OTEL_LOGS_EXPORTER=none ; les logs restent sur stdout et les événements de requête sont attachés aux traces. Quand AppSignal supportera les logs OTLP, retirer cette variable. Pour un autre backend OTLP, OTEL_LOGS_EXPORTER=otlp fonctionne.

Requêtes tracées #

Chaque requête (hors /health et assets) produit un span http_request avec la méthode, le chemin, le statut et la durée. Les logs émis pendant la requête sont corrélés au span.

Sécurité et limites #

  • Il n'y a pas d'authentification : toute personne qui accède à l'URL peut lire et modifier les données. Ne pas exposer l'application directement sur Internet ; utiliser un VPN ou un reverse proxy avec mot de passe.
  • Pas de conversion d'unités, d'arrondi d'achat, de gestion de stock, de budget, d'allergènes, d'images ni de sous-recettes.
  • Les quantités sont affichées avec deux décimales maximum, avec une virgule française.
  • Toasty 0.11 n'émet pas de clés étrangères SQLite dans les migrations : la cohérence est assurée par les transactions et les garde-fous applicatifs, pas par le schéma.
  • Les listes et la liste de courses font plusieurs petites requêtes par élément (N+1). C'est adapté à un petit collectif ; à optimiser si les données grossissent.
  • La confirmation des suppressions utilise hx-confirm côté navigateur. Sans JavaScript, le bouton reste explicite mais la suppression est immédiate.
  • Une seule instance et un seul fichier SQLite sont prévus. C'est adapté à un petit collectif, pas à un déploiement multi-utilisateurs à forte concurrence.