- Rust 85%
- TypeScript 14%
- Docker <1%
- Shell <1%
- CSS <1%
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 dansassets/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
Nconvives, elles sont multipliées parN / 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-bookwormpuisgcr.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
/healthviacantoche healthcheck; - écrit la base dans
/data/cantoche.dbpar 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-confirmcô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.