Premier démarrage en local

Vous êtes développeur·se et vous venez de cloner le dépôt Kirexo pour la première fois. À la fin de ce tutoriel, vous aurez la stack Docker qui tourne sur votre machine, la page d'accueil affichera un « Hello World » rendu par un Symfony UX Twig Component, et vous saurez où trouver les interfaces d'administration des services backing (RabbitMQ, Mailpit, Typesense).

Comptez dix à quinze minutes, en grande partie occupées par le téléchargement des images Docker au premier lancement.

Prérequis

Sur votre machine, vous avez uniquement besoin de :

• git
• docker
• docker-compose
• castor — task runner
• jq
• glab — CLI GitLab

Rien d'autre. Pas de PHP, pas de Node, pas de Composer, pas de Yarn installés en local : tout s'exécute dans les conteneurs. C'est un choix volontaire pour garantir que chaque développeur·se travaille dans le même environnement.

Étape 1 — Récupérer le code

git clone git@gitlab.com:shaurifr/kirexo.git
cd kirexo

Étape 2 — Démarrer la stack Docker

La cible docker:up construit les images si besoin et démarre tous les services (FrankenPHP, Postgres, Redis, RabbitMQ, Typesense, Gotenberg, Mailpit).

castor docker:up --build

Au premier lancement, Docker télécharge les images (Postgres, Redis, RabbitMQ, Typesense, Gotenberg, Mailpit) et construit l'image PHP/FrankenPHP. C'est le seul moment long ; les lancements suivants prennent quelques secondes.

Par défaut, castor docker:up attend que tous les healthchecks soient verts avant de rendre la main. Si vous voulez un démarrage rapide sans attendre, ajoutez --no-wait.

Étape 3 — Installer les dépendances applicatives

Une fois la stack démarrée, installez les dépendances applicatives :

castor install

Cette cible enchaîne trois actions, toutes exécutées dans le conteneur php — vous n'avez rien à installer côté hôte :

1. composer install — télécharge les paquets PHP dans vendor/.
2. bin/console importmap:install — installe les assets JavaScript gérés par Symfony Asset Mapper.
3. bin/console tailwind:build — compile le CSS Tailwind vers public/.

Téléchargement du binaire Tailwind au premier build

La troisième étape télécharge au premier appel le binaire Tailwind standalone (Go, environ 30 Mo). Ce binaire est mis en cache sur le filesystem hôte via le volume monté dans le conteneur : il n'est pas re-téléchargé aux castor docker:down / castor docker:up suivants, ni après un redémarrage de votre machine.

Étape 4 — Ouvrir l'application

Rendez-vous sur http://localhost. Vous devez voir une page qui affiche Hello World ainsi qu'un sous-titre de bienvenue. Ce contenu est rendu par un Symfony UX Twig Component (voir src/Twig/Components/HelloWorld.php) intégré dans le template templates/home/index.html.twig.

Si la page s'affiche, votre installation est fonctionnelle. Bravo !

Supprimer l'avertissement HTTPS

FrankenPHP expose aussi HTTPS sur https://localhost avec une CA locale générée par Caddy. Votre navigateur affichera un avertissement à la première visite.

Pour l'éliminer définitivement, installez le certificat dans le trust store de votre OS :

castor cert:trust

La commande extrait la CA Caddy depuis le conteneur et l'installe automatiquement (macOS, Linux, Windows). Un mot de passe administrateur vous sera demandé. Après redémarrage du navigateur, https://localhost s'affiche sans avertissement.

Firefox nécessite une étape supplémentaire : soit importer le fichier var/caddy-root.crt manuellement (Paramètres → Vie privée → Certificats → Importer, cocher « Autorités »), soit activer security.enterprise_roots.enabled = true dans about:config pour qu'il lise le trust store OS.

Les autres interfaces disponibles

La stack dev expose plusieurs UI utiles au quotidien :

Service	URL	Identifiants par défaut
Application	http://localhost	—
Documentation (mkdocs live)	http://localhost:8000	—
RabbitMQ (management)	http://localhost:15672	guest / guest
Mailpit (boîte mail de dev)	http://localhost:8025	—
Typesense (santé)	http://localhost:8108/health	clé API dans .env

Les mails envoyés par l'application en dev sont capturés par Mailpit — aucun email ne part réellement sur Internet.

Étape 5 — Lire cette documentation en local

La documentation est déjà servie par la stack Docker : un service docs (image squidfunk/mkdocs-material) démarre automatiquement avec castor docker:up et expose mkdocs en live-reload sur http://localhost:8000. Vos modifications dans docs/ ou mkdocs.yml sont prises en compte à chaud.

Vous n'avez donc rien à lancer en plus en dev.

Changer le port

Définissez MKDOCS_PORT dans votre .env.local si le port 8000 est déjà pris.

Pour générer le site statique (publication, CI), utilisez castor docs:build — il produit le rendu HTML dans ./site/ sans démarrer de serveur.

Et ensuite ?

• Lancer les tests — unitaires, intégration, E2E.
• Référence des commandes Castor — inventaire complet du task runner.
• Architecture — pourquoi ce stack, pourquoi CQRS, pourquoi des plugins.

En cas de pépin

• Le port 80 est déjà utilisé — un autre service écoute sur le port 80 de votre machine (souvent un Apache ou un autre projet Docker). Arrêtez-le, ou surchargez les ports en définissant HTTP_PORT, HTTPS_PORT, HTTP3_PORT dans un fichier .env.local.
• castor: command not found — installez Castor en suivant la doc officielle.
• La page http://localhost ne répond pas — vérifiez l'état des conteneurs avec docker compose ps. Si le conteneur php n'est pas healthy, consultez ses logs avec castor docker:logs php.
• La documentation http://localhost:8000 n'est pas accessible — le service docs démarre avec la stack mais peut mettre quelques secondes. Si elle reste inaccessible : vérifiez son état avec docker compose ps docs et ses logs avec castor docker:logs docs.