Aller au contenu

Premier démarrage pour développer

Si vous voulez seulement installer Kirexo pour l'utiliser, suivez plutôt Installer Kirexo chez soi.

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 de la plateforme s'affichera dans votre navigateur, et vous saurez où trouver la documentation servie en local et la boîte mail de développement.

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 le proxy hôte (une seule fois par poste)

Tout l'environnement de développement est servi par un unique proxy Caddy, publié sur 127.0.0.1:80 et 127.0.0.1:443. C'est lui qui route chaque nom en .localhost vers la bonne stack. Il vit dans son propre projet Compose, partagé par tous vos checkouts du dépôt.

castor proxy:up

C'est un geste unique sur la machine : ensuite, vous n'y revenez que pour un castor proxy:status en cas de doute. La cible est idempotente — la relancer ne casse rien.

Étape 3 — Démarrer la stack Docker

La cible docker:up construit les images si besoin, démarre les services du dépôt (FrankenPHP, Postgres, mkdocs) et la stack mutualisée kirexo-shared (proxy sortant, Redis, RabbitMQ, Typesense, Gotenberg, Mailpit) que se partagent tous vos checkouts.

castor docker:up --build

Au premier lancement, Docker télécharge les images 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.

En fin de cible, les URL servies sont affichées. La stack ne publie aucun port : elle n'est joignable qu'à travers le proxy de l'étape 2.

Et si je travaille sur un ticket ?

Ce tutoriel démarre le dépôt principal. Pour travailler sur un ticket sans quitter cette stack, Kirexo utilise des worktrees git, chacun avec sa propre stack isolée et ses propres URL : castor wt:up <ticket>. Le parcours complet est dans Créer et détruire un worktree.

Étape 4 — 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 5 — Préparer la base de données

La stack démarre avec une base vide : ni schéma, ni données. Appliquez les migrations, puis chargez les fixtures de développement :

castor doctrine:migrate
castor fixtures:load

La première commande crée les tables ; la seconde les peuple (comptes de démonstration, carnets, articles publiés). Sans elles, la page d'accueil échouerait sur une table absente.

fixtures:load purge la base

Sans --append, doctrine:fixtures:load vide la base avant de recharger. C'est ce qu'on veut sur une installation neuve, jamais sur une base où vous avez du travail en cours.

Les worktrees, eux, s'en chargent seuls

castor wt:up <ticket> applique les migrations à chaque passage et charge les fixtures uniquement si la base est vierge. Cette étape manuelle ne concerne donc que le dépôt principal.

Étape 6 — Ouvrir l'application

Rendez-vous sur https://app.main.localhost. Vous devez voir l'accueil de la plateforme, rendu par templates/home/index.html.twig. Sur une base fraîchement fixturée, l'écran affiche le fil des derniers articles publiés ; sur une base vide, il bascule sur son état vierge — « Votre carnet est prêt. » et les trois premiers pas.

main est le nom sous lequel le proxy route le dépôt principal — comme la branche que porte votre arbre de travail. https://localhost y redirige d'ailleurs en 308.

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

L'avertissement HTTPS de la première visite

Le proxy signe chaque nom en .localhost avec sa propre CA locale. Tant que cette CA n'est pas connue de votre système, votre navigateur affiche un avertissement à la première visite : acceptez l'exception de sécurité, la page s'affiche ensuite normalement.

Installez cette CA dans le trust store de votre OS pour ne plus l'avoir du tout :

castor cert:trust

La commande extrait la racine de la CA du proxy dans var/caddy-root.crt et l'installe automatiquement (macOS, Linux, Windows). Un mot de passe administrateur vous sera demandé. Le geste est unique : la racine vaut dix ans et couvre tous vos worktrees, présents et futurs.

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.

Une fois la CA installée, plus aucune URL de développement n'avertit — c'est pour cela que toutes portent un préfixe de service (app., docs., mailpit.) : le raisonnement est dans Pourquoi tout nom servi a au moins deux labels.

Les autres interfaces disponibles

Trois URL sont servies par le proxy pour le dépôt principal :

Service URL
Application https://app.main.localhost
Documentation (mkdocs live-reload) https://docs.main.localhost
Mailpit (boîte mail de dev) https://mailpit.main.localhost

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

PostgreSQL, RabbitMQ et Typesense ne sont pas joignables directement depuis l'hôte

Aucun service de backing ne publie de port : le seul conteneur qui publie quoi que ce soit est le proxy. Pour un client SQL ou l'UI de management RabbitMQ, passez par docker compose exec (ou un tunnel ponctuel) — jamais en réintroduisant un bloc ports:, qui rouvrirait la surface que ce dispositif ferme et rendrait deux stacks à nouveau incompatibles.

Note : en profil light, RabbitMQ et Typesense vivent dans le projet mutualisé kirexo-shared, pas dans la stack du dépôt — le docker compose exec doit alors viser ce projet.

Étape 7 — Lire cette documentation en local

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

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

Pour générer le site statique (publication, CI), utilisez castor docs:build — il produit le rendu HTML dans var/docs-build/ sans démarrer de serveur, et en mode --strict : une erreur mkdocs (lien cassé, snippet introuvable) fait échouer la commande.

Et ensuite ?

En cas de pépin

  • Le port 80 ou 443 est déjà utilisé — un autre service écoute sur la loopback de votre machine (souvent un Apache, ou un autre projet Docker). Le seul conteneur qui publie quoi que ce soit ici est le proxy de l'étape 2, et ses ports ne sont pas surchargeables : arrêtez le service concurrent. castor proxy:status nomme ce qui est en place côté proxy.
  • castor: command not found — installez Castor en suivant la doc officielle.
  • https://app.main.localhost ne répond pas — vérifiez d'abord que le proxy tourne (castor proxy:status), puis l'état des conteneurs (docker compose ps). Si le conteneur php n'est pas healthy, consultez ses logs avec castor docker:logs php. Un diagnostic complet des deux côtés est donné par castor doctor.
  • https://app.main.localhost répond mais l'application plante — la base n'est probablement ni migrée ni fixturée : rejouez l'étape 5.
  • https://app.main.localhost rend 502 — le proxy route bien, mais aucun conteneur ne porte l'alias réseau php-main. C'est l'état d'un poste installé avant le renommage des URLs : suivez Migrer un poste existant vers les URLs app..
  • https://docs.main.localhost 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.
  • Le navigateur ne résout pas les noms en .localhost — c'est le cas sur un poste sans systemd-resolved. castor proxy:status sonde la résolution et imprime la ligne /etc/hosts à ajouter.