Développement¶

Prérequis¶

Outil	Version / remarque
Rust + Cargo	≥ 1.85 (le crate utilise l'édition 2024)
Node.js + npm	Le `Dockerfile` du front utilise Node 20
Docker + Docker Compose	Pour la base (et éventuellement toute la stack)
Application Clerk	Clé publique et clé secrète de la même application
`sqlx-cli` ou `psql`	Pour appliquer la migration

Variables d'environnement¶

Les fichiers todoback/.env et todofront/.env sont ignorés par Git. Ils se créent à partir des .env.exemple.

Pièges des fichiers .env.exemple

todoback/.env.exemple nomme la variable de base DB_CONNECTION, alors que le code lit DATABASE_URL. Renomme-la, sinon l'API panique au démarrage.
Ne réutilise pas les valeurs présentes dans les .env.exemple : renseigne tes propres clés Clerk et ta propre URL de base.

Backend (`todoback/.env`)¶

Variable	Obligatoire	Rôle
`TEST`	oui	Lue au démarrage (panique si absente) mais inutilisée : n'importe quelle valeur convient
`DATABASE_URL`	oui	URL PostgreSQL, format `postgres://<utilisateur>:<mot_de_passe>@<hôte>:<port>/<base>`
`CLERK_SECRET_KEY`	oui	Clé secrète Clerk, utilisée pour récupérer les clés de vérification des JWT

Frontend (`todofront/.env`)¶

Variable	Obligatoire	Rôle
`VITE_CLERK_PUBLISHABLE_KEY`	oui	Clé publique Clerk passée au `ClerkProvider`
`VITE_BACKEND_URL`	oui	URL de base de l'API telle que le navigateur la voit (ex. `http://localhost:8080`), utilisée comme `baseURL` axios

Variables VITE_* = variables de build

Vite les inscrit en dur dans le bundle JavaScript au moment du build : toute modification impose de reconstruire le front, et elles sont lisibles par n'importe quel visiteur. N'y mets jamais de secret.

Lancer en local¶

Tout avec Docker ComposeBack et front hors Docker

cp todoback/.env.exemple todoback/.env     # puis DB_CONNECTION -> DATABASE_URL, et remplir
cp todofront/.env.exemple todofront/.env   # puis remplir
docker compose up -d --build

Puis appliquer la migration et ouvrir http://localhost:3000.

Dans ce mode :

DATABASE_URL doit viser l'hôte postgres (nom du service) sur le port 5432, avec les identifiants POSTGRES_USER, POSTGRES_PASSWORD et POSTGRES_DB définis dans docker-compose.yaml.
VITE_BACKEND_URL doit valoir http://localhost:8080 : c'est le navigateur, sur la machine hôte, qui appelle l'API.

# 1. Base seule
docker compose up -d postgres

# 2. API (DATABASE_URL vers localhost:5432)
cd todoback
cargo run

# 3. Front, dans un autre terminal
cd todofront
npm install
npm run dev

Puis appliquer la migration et ouvrir http://localhost:5173.

Services du `docker-compose.yaml`¶

Service	Conteneur	Build / image	Ports hôte:conteneur	Configuration
`postgres`	`my_postgres_todo`	`postgres:latest`	`5432:5432`	Identifiants en clair dans le fichier, `TZ=Europe/Paris`, volume `postgres_data`
`todoback`	`todoback`	`todoback/Dockerfile` (build Rust puis `debian:bookworm-slim`)	`8080:8080`	`env_file: todoback/.env`
`todofront`	`todofront`	`todofront/Dockerfile` (build Node 20 puis Nginx)	`3000:80`	`env_file: todofront/.env`

Front sous Compose : les variables viennent du fichier .env copié au build

env_file ne s'applique qu'au conteneur Nginx en cours d'exécution, pas au build. Le build Vite lit todofront/.env parce que ce fichier est copié dans le contexte (COPY . ., et .env n'est pas exclu par .dockerignore). Après modification : docker compose up -d --build todofront.

Ordre de démarrage

todoback dépend de postgres sans condition de santé ni politique de redémarrage. Si la base n'accepte pas encore les connexions, l'API panique (error whit db connection) et le conteneur s'arrête : relance-le avec docker compose up -d todoback.

Migrations¶

L'API n'applique pas les migrations elle-même. Sans la table todos, elle démarre normalement mais toutes les requêtes authentifiées répondent 500 Unable to fetch users.

sqlx-clipsql (conteneur Compose)

cargo install sqlx-cli   # une seule fois
# depuis la racine du dépôt (dossier migrations/)
DATABASE_URL="postgres://<utilisateur>:<mot_de_passe>@localhost:5432/<base>" sqlx migrate run

docker exec -i my_postgres_todo \
  psql -U <utilisateur> -d <base> < migrations/20251107230825_init.sql

Ne mélange pas les deux méthodes

sqlx migrate run enregistre les migrations appliquées dans la table _sqlx_migrations, psql non. Après un passage par psql, un sqlx migrate run retenterait le CREATE TABLE et échouerait.

CORS en local¶

L'API n'accepte que ces origines (voir todoback/src/routes/mod.rs) :

Origine	Usage
`http://localhost:5173`	`npm run dev`
`http://127.0.0.1:5173`	`npm run dev`
`http://localhost:3000`	Front sous Docker Compose
`https://todo.dunkan.xyz`	Production

Ouvrir le front sur une autre origine (ex. http://127.0.0.1:3000 ou un autre port Vite) provoque une erreur CORS dans le navigateur : il faut ajouter l'origine à la liste et relancer l'API.

Commandes utiles¶

Dossier	Commande	Effet
`todoback/`	`cargo run`	Lance l'API sur `0.0.0.0:8080`
`todoback/`	`cargo build --release`	Binaire `target/release/todoback`
`todofront/`	`npm run dev`	Serveur de dev Vite (HMR)
`todofront/`	`npm run build`	Build de production dans `dist/`
`todofront/`	`npm run preview`	Sert le build localement
`todofront/`	`npm run lint`	ESLint

À compléter

Le dépôt ne contient aucun test automatisé ni pipeline de CI.

Erreurs fréquentes au démarrage de l'API¶

Symptôme	Cause probable
Panique `called Result::unwrap() on an Err value` dès le lancement	`TEST` ou `DATABASE_URL` absente (variable restée nommée `DB_CONNECTION`)
Panique `error whit db connection`	Base injoignable ou `DATABASE_URL` incorrecte
Panique `CLERK_SECRET_KEY must be set`	Clé secrète Clerk absente
Toutes les requêtes en `401`	Jeton absent, expiré, ou clés Clerk du front et du back issues d'applications différentes
Toutes les requêtes en `500`	Migration non appliquée ou erreur SQL (détail dans les logs de l'API)