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 — installe les dépendances PHP
php bin/console app:setup — génère les clés JWT, exécute les migrations Doctrine, importe les ~140k villes GeoNames
npm install — 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 build`	Rebuild les images et redémarre les conteneurs
`mise run docker:down`	`mise stop`	Arrête et supprime tous les conteneurs
`mise run logs`	`mise logs`	Affiche les logs en temps réel (tous les services)
`mise run api:init`	`mise api:init`	Réinitialise l'API uniquement (Composer, JWT, migrations, GeoNames)
`mise run candidate:init`	`mise candidate:init`	Installe les dépendances npm de l'app candidat
`mise run recruiter:init`	`mise 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 complet + tout seeder (utile après une migration qui change le schéma)
mise seed:fresh

mise seed:fresh après une migration — si le schéma a changé, les données existantes peuvent entrer en conflit avec les nouvelles contraintes. Un fresh reset garantit un état propre.

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 et régénérer :

rm api/config/jwt/*.pem
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 build