Démarrage¶

Prérequis¶

Outil	Rôle
Docker Desktop	Fait tourner tous les services (API, frontends, PostgreSQL, Redis, Mailpit) dans des conteneurs isolés — aucun service n'est installé directement sur ta machine
mise	Gestionnaire de tâches — remplace les Makefiles. Lance les commandes du projet (build, tests, seed, lint) depuis la racine du monorepo

Installation¶

1. Cloner le dépôt¶

git clone git@github.com:wonderwork-io/wonderwork.git
cd wonderwork

2. Configurer les variables d'environnement¶

Deux fichiers d'environnement distincts — l'un pour Docker Compose (racine), l'autre pour Symfony (api/).

`.env` — Infrastructure Docker Compose¶

Contrôle les credentials et ports des conteneurs. Partagé entre tous les services.

cp .env.sample .env

Valeurs à définir :

POSTGRES_PASSWORD=password          # Mot de passe PostgreSQL (choisir librement en dev)
JWT_PASSPHRASE=                     # openssl rand -hex 16

`api/.env.local` — Secrets Symfony et APIs externes¶

Variables spécifiques à l'application Symfony — non exposées dans Docker Compose.

cp api/.env.local.sample api/.env.local

Valeurs à définir :

CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'
APP_SECRET=                         # openssl rand -hex 32
FRANCE_TRAVAIL_CLIENT_ID=           # API ROME — nécessaire pour l'import du référentiel métiers
FRANCE_TRAVAIL_CLIENT_SECRET=

API France Travail

Les identifiants France Travail sont nécessaires pour importer le référentiel ROME (~1 584 fiches métiers, ~13 000 appellations). Sans eux, l'autocomplete de métiers ne fonctionnera pas. Créer un compte sur francetravail.io pour obtenir les credentials.

3. Installer¶

mise install

Cette commande unique exécute dans l'ordre :

docker compose up -d --build — construit les images Docker et démarre tous les conteneurs
composer install et npm install côté API — installe les dépendances backend et assets API
php bin/console app:setup — génère les clés JWT, exécute les migrations Doctrine, importe les ~140k villes GeoNames
npm install côté candidate et recruiter — installe les dépendances des apps frontend

L'import GeoNames prend 2–3 minutes au premier lancement — c'est normal. Les exécutions suivantes le skipent si la table cities est déjà remplie.

Services¶

Après mise install, tous les services sont accessibles :

Service	URL	Description
API	http://localhost:8000	API Symfony — endpoints REST
API docs (OpenAPI)	http://localhost:8000/v1/docs	Interface Swagger interactive
App Candidate	http://localhost:3000	Frontend candidat (Next.js)
App Recruteur	http://localhost:3001	Frontend recruteur (Next.js)
Mailpit	http://localhost:8025	Catch-all emails de dev — tous les emails envoyés par l'API atterrissent ici

Commandes mise¶

Développement quotidien¶

Commande	Alias	Ce qu'elle fait
`mise run dev`	`mise start`	Démarre les conteneurs Docker sans rebuild
`mise run install`	`mise install`	Installation complète — build + init API + frontends
`mise run docker:up`	`mise rebuild`	Rebuild les images et redémarre les conteneurs
`mise run docker:down`	`mise stop`	Arrête les conteneurs sans supprimer les volumes
`mise run docker:reset`	—	Arrête Docker et supprime les volumes nommés
`mise run reset`	—	Reset complet local : volumes Docker, dépendances, DB, migrations, GeoNames
`mise run reset:seed`	—	Reset complet local puis chargement de toutes les stories API
`mise run logs`	`mise logs`	Affiche les logs en temps réel (tous les services)
`mise run api:init`	—	Initialise l'API uniquement (Composer, npm API, JWT, migrations, GeoNames)
`mise run api:migrate`	—	Rejoue les migrations Doctrine dans le container en cours
`mise run candidate:init`	—	Installe les dépendances npm de l'app candidat
`mise run recruiter:init`	—	Installe les dépendances npm de l'app recruteur

Qualité et lint¶

Commande	Alias	Ce qu'elle fait
`mise run quality`	`mise quality`	Lance PHPStan (niveau 8), ECS, ESLint et type-check TypeScript
`mise run lint:fix`	`mise fix`	Auto-corrige le code PHP (ECS) et TypeScript (ESLint)
`mise run leaks`	`mise leaks`	Scanne le code pour des secrets exposés accidentellement (Gitleaks)

mise quality avant chaque PR — même pipeline que la CI. Détecter les erreurs localement évite un aller-retour CI.

Seed — Données de développement¶

Le seed charge des données réalistes dans la base pour travailler avec un environnement fonctionnel. Les données sont organisées en stories — chaque story correspond à un scénario ou un acteur.

Commande	Alias	Ce qu'elle fait
`mise run api:seed`	`mise seed`	Charge une story spécifique
`mise run api:seed:all`	`mise seed:all`	Charge toutes les stories
`mise run api:seed:fresh`	`mise seed:fresh`	Remet la base à zéro puis charge toutes les stories

# Charger une story spécifique
mise seed -- candidates

# Reset DB + toutes les stories, sans supprimer les volumes Docker
mise seed:fresh

# Reset complet de l'environnement local + toutes les stories
mise run reset:seed

Après une migration ou une modification des données de référence ROME — utiliser mise run reset:seed si la base doit être reconstruite depuis zéro. Cette commande supprime les volumes Docker, réinstalle les dépendances, rejoue toutes les migrations et recharge les seeds. Utiliser mise seed:fresh seulement quand un reset de base suffit et que les volumes peuvent être conservés.

Emails de test¶

mise run email:test

Envoie un email de test vers Mailpit pour vérifier que le pipeline email (MJML → Mailer → Mailpit) fonctionne correctement. Accéder à http://localhost:8025 pour le visualiser.

Documentation locale¶

Commande	Alias	Ce qu'elle fait
`mise run docs:install`	—	Crée le venv Python et installe MkDocs Material
`mise run docs:serve`	`mise docs`	Lance la prévisualisation de la doc avec hot-reload sur http://127.0.0.1:8080

Stack de test¶

Les tests tournent sur une stack isolée (profil Docker e2e) indépendante de l'environnement de développement. Les deux stacks coexistent sans conflit de ports — tu peux développer et lancer les tests simultanément.

Service	URL de test
API test	http://localhost:8001
Candidate test	http://localhost:3010
Recruiter test	http://localhost:3011

Commande	Ce qu'elle fait
`mise run test:init`	Démarre la stack de test et l'initialise (migrations, import GeoNames si absent)
`mise run test`	Lance Behat (API) + Vitest (candidate + recruiter)
`mise run test:e2e`	Lance les tests E2E Playwright

# Premier lancement — plus long (import GeoNames en DB test)
mise test

# Runs suivants — rapides (import skipé, données déjà présentes)
mise test

Git hooks (Husky)¶

Un hook pre-commit s'exécute automatiquement avant chaque commit :

Gitleaks — scanne les fichiers stagés pour des secrets exposés (tokens, clés privées, mots de passe)
lint-staged — applique Prettier et ESLint uniquement sur les fichiers modifiés

Ces hooks évitent de committer accidentellement des secrets ou du code malformaté. Ils sont installés automatiquement par mise install.

# Bypass en urgence (à éviter)
git commit --no-verify

Problèmes courants¶

Port 5432 déjà utilisé

Un PostgreSQL local tourne sur le même port que le conteneur. Arrêter le service local : sudo service postgresql stop, ou changer le port dans docker-compose.yml.

Erreur JWT au login

Les clés JWT ont été générées avec une autre passphrase que celle dans .env. Supprimer les clés puis régénérer avec mise api:init.

Translation / class not found après un git pull

Une nouvelle dépendance PHP a été ajoutée. Réinstaller :

docker compose exec api composer install

Cache Behat périmé

Le cache de l'environnement de test est désynchronisé. Vider :

docker compose exec api php bin/console cache:clear --env=test

Conteneurs qui ne démarrent pas après un changement de Dockerfile

Docker Compose utilise l'image cachée. Forcer le rebuild :

mise rebuild

Environnement local incohérent après un changement de migrations ou de données ROME

Repartir d'une base neuve et recharger les seeds :

mise run reset:seed