Processus

L’onglet Processus (P) lance le projet depuis Joppa : ses serveurs de dev (scripts dev de package.json, cibles Nx, serveur PHP) et son infrastructure (services Docker Compose). Chaque processus a son état, son port et ses logs.

Analyser le projet

La première fois, cliquez sur Analyser le projet, en haut de la page du projet (à côté d’Ouvrir) ou dans l’onglet. Tant que l’analyse n’est pas faite, Joppa ne lance rien : les domaines restent hors ligne jusqu’à ce que vous démarriez le serveur. Joppa lit package.json, les workspaces et le fichier Docker Compose, puis montre Ce que Joppa a compris du projet. Rien ne démarre avant que vous validiez.

Colonne	Contenu
Dans « Tout démarrer »	Décochez un processus pour qu’il ne parte pas avec les autres ; il reste lançable seul
Processus	Son nom : web, api, postgres
Commande	bun run dev, ou le service Compose
Port	Modifiable
D’où vient le port	script, config, code, .env, compose ou défaut
Prêt quand	Pour un serveur de dev avec port : le chemin HTTP que Joppa demande pour savoir qu’il est prêt (/ par défaut), ou tcp

La ligne « attend … » indique les dépendances : un serveur de dev attend que les conteneurs Compose dont il dépend soient prêts.

+ action, sous la commande d’un serveur de dev, lui ajoute des actions.

Comment le port est trouvé

Dans cet ordre :

1. une variable avec valeur par défaut dans le script (${PORT:-3000}) : Joppa la renseigne ;
2. --port, -p ou PORT= dans le script ;
3. port: dans la config du framework (vite.config, astro.config), y compris sur une ligne (server: { port: 5400 }), ou options.port d’une cible Nx ;
4. PORT dans le .env ;
5. le port par défaut du framework : Vite et VitePress 5173, Astro 4321, Next.js, Nuxt, Create React App et Docusaurus 3000, Angular 4200, Wrangler 8787, Vue CLI 8080, Gatsby 8000, Storybook 6006, Expo 8081.

Pour un autre serveur Node, Joppa cherche le port dans le code (.listen(3000), process.env.PORT ?? 3000).

Le gestionnaire de paquets vient du lockfile, sinon du champ packageManager, sinon npm.

Le script de chaque package

Joppa prend le script dev du package ; à défaut, develop, serve, ou un start qui lance un serveur de dev (react-scripts start, ng serve, expo start…). Un start de production (node dist/server.js) est ignoré.

Le serveur PHP

Projet	Indice	Commande
Laravel	fichier artisan	php artisan serve --host=127.0.0.1 --port=${SERVER_PORT:-8000}
Symfony, autre PHP	public/index.php et composer.json	php -S 127.0.0.1:${PORT:-8000} -t public

Le port vient de SERVER_PORT (Laravel) ou PORT dans le .env, sinon 8000. Le php est celui de la version épinglée.

Les workers Laravel

À côté de php artisan serve, Joppa propose les processus de fond dont l’application se sert, lus dans composer.json, le .env et le code :

Processus	Quand	Commande	Coché
queue	QUEUE_CONNECTION n’est pas sync (Laravel 11 et plus : database par défaut)	php artisan queue:work, ou celle de composer run dev (queue:listen --tries=1 dans les kits de démarrage, qui relit le code à chaque job)	oui ; proposé décoché avec sync
horizon	laravel/horizon est installé	php artisan horizon, à la place de queue quand la file passe par Redis	si QUEUE_CONNECTION=redis
scheduler	toujours	php artisan schedule:work	si l’application planifie une tâche (Schedule:: dans routes/console.php, $schedule-> dans le Kernel)
reverb	laravel/reverb est installé	php artisan reverb:start --host=127.0.0.1 --port=${REVERB_SERVER_PORT:-8080}	si BROADCAST_CONNECTION=reverb
pail	laravel/pail est installé	php artisan pail --timeout=0	non : Joppa affiche déjà les logs

Ce sont des processus sans port, sauf Reverb : son port vient de REVERB_SERVER_PORT dans le .env, sinon 8080, et Joppa fixe la variable pour qu’un worktree le déplace. Un processus décoché reste dans la liste et se lance à la main.

Les monorepos

Joppa trouve les packages là où le dépôt les déclare :

Fichier	Forme
package.json	workspaces (npm, yarn, bun), en liste ou { "packages": [...] }
pnpm-workspace.yaml	packages:
lerna.json	packages (par défaut packages/*)
nx.json	chaque project.json du dépôt, ses cibles serve / dev, et celles que les plugins Nx déduisent (@nx/vite/plugin, @nx/next/plugin)

Les motifs apps/*, packages/** (à toute profondeur) et les exclusions !packages/legacy sont compris ; node_modules, dist et les dossiers cachés sont ignorés. Une cible Nx se lance avec nx run <projet>:<cible>.

Le script dev de la racine dit quelle tâche lancer dans chaque package et lesquels :

Script racine	Tâche	Packages
turbo dev, turbo run dev, turbo watch dev	dev	tous ceux qui l’ont
turbo run start:dev --filter=web...	start:dev	web
nx run-many -t serve -p shop admin	serve	shop, admin
nx serve shop, nx run shop:serve	serve	shop
pnpm -r --parallel dev, pnpm --filter ./apps/* dev	dev	tous / ceux de apps/
bun run --filter '@acme/*' dev	dev	ceux du scope @acme
npm run dev -w apps/web -w apps/api	dev	web, api

Un filtre désigne un package par son nom, son dossier ou un motif (apps/*, @acme/*) ; ..., ^, {…} et les exclusions !docs de Turborepo sont compris. Un package hors du dev racine reste décoché, sauf si un domaine pointe vers lui.

Quand le script dev de la racine lance plusieurs apps d’un coup, Joppa propose :

• Les lancer séparément · un état et des logs par app (recommandé) ;
• Tel quel : la commande racine, dans un seul terminal.

Enregistrer : sur la machine ou pour l’équipe

• Enregistrer garde la configuration dans Joppa, sur cette machine.
• Cochez Écrire joppa.toml dans le dépôt pour l’équipe pour la partager : elle est écrite dans un fichier joppa.toml à la racine du projet, à commiter. Quand ce fichier existe, c’est lui qui fait foi. Voir la référence de joppa.toml. Pour partager aussi les domaines, les services, la base et les versions, utilisez le lien Partager la configuration dans joppa.toml sous la liste des processus.

Enregistrer et démarrer lance tout de suite.

Démarrer et arrêter

• ▶ Tout démarrer / ■ Tout arrêter en haut de la page du projet, ou depuis la palette ⌘ K (« Tout démarrer : monprojet »). Dès qu’un processus tourne, le bouton devient ■ Tout arrêter.
• Chaque processus se démarre, s’arrête ou se redémarre seul, dans l’onglet ou depuis la palette.

Les processus sont groupés en Applications (scripts « dev ») et Infrastructure (Docker Compose, lancé avec docker compose up -d --wait : Joppa attend les healthchecks). L’en-tête indique l’ordre de démarrage et combien sont lancés. Chaque groupe a son propre bouton ▶ Tout démarrer / ■ Tout arrêter, qui ne touche que ses processus : lancer l’infrastructure sans les applications, par exemple. Comme celui du projet, il laisse de côté les processus décochés de « Tout démarrer ».

État	Signification
arrêté	—
arrêt…	Arrêt demandé, le processus n’est pas encore sorti
en attente	Attend un processus dont il dépend
démarrage	Lancé, il ne répond pas encore (voir Quand un processus est prêt)
en cours	Lancé (processus sans port)
en ligne	Il répond à une requête HTTP sur son port
échec	S’est arrêté avec une erreur
lancé hors de Joppa	Le port est déjà servi par un processus que Joppa n’a pas lancé
sans Docker	Service Compose, mais aucun runtime ne tourne
en veille	Arrêté par Joppa faute de requêtes : la prochaine le réveille (voir Mise en veille)

Le compteur ▶ 6/7 à côté du projet, dans la barre latérale et sur sa carte de la page Projets, dit combien de processus de « Tout démarrer » sont lancés ; la barre d’état en bas de la fenêtre fait le total de tous les projets (6/7 processus). La couleur du ▶ : vert quand tout tourne, orange quand certains sont arrêtés, en démarrage ou lancés hors de Joppa, rouge seulement quand l’un a échoué. Survolez le compteur pour le détail. Un z bleu remplace le ▶ quand les serveurs de dev du projet sont en veille.

Si le port est pris par un autre programme, Joppa le dit et propose Libérer le port.

L’arrêt envoie SIGTERM, puis SIGKILL après 6 secondes, à tout ce que le script a lancé. Un serveur de dev qui continue après la fin du script qui l’a démarré reste suivi par Joppa : il garde son journal, son état et son bouton d’arrêt.

Depuis le terminal : joppa procs, joppa start|stop|restart <projet> [processus] et joppa logs <projet> [processus] (voir La commande joppa). Un assistant comme Claude Code ou Cursor fait de même avec les outils list_processes, start_process, restart_process, process_logs et run_process_action du serveur MCP.

Lancer à l’ouverture de Joppa

L’interrupteur Lancer à l’ouverture de Joppa fait un « Tout démarrer » du projet à chaque lancement de Joppa. C’est une préférence de votre machine : elle n’est jamais écrite dans joppa.toml.

Si un joppa.toml arrive par git pull avec des commandes modifiées, Joppa ne les lance pas tout seul : une notification indique que le projet n’a pas été démarré. Vérifiez les commandes, puis cliquez sur Tout démarrer : le démarrage à l’ouverture reprend ensuite normalement.

Relancer après un plantage

Le réglage Relancer après un plantage choisit combien de fois Joppa relance un serveur de dev qui plante : jamais, 1, 2, 3 (par défaut), 5 ou 10 fois.

• L’attente double entre deux relances : 1 s, 2 s, 4 s, 8 s… jusqu’à 30 s.
• Le compteur repart à zéro après 60 secondes de fonctionnement stable.
• Au-delà, Joppa abandonne et l’indique : « a replanté après 3 relances : Joppa abandonne. »
• Un arrêt demandé par vous annule une relance en attente.

Ce réglage ne concerne que les serveurs de dev (pas les conteneurs Compose) et reste propre à votre machine.

Réparer un processus en échec

Quand un processus s’arrête pour de bon (Joppa a abandonné après ses relances, ou la relance est désactivée), une bannière rouge apparaît en haut de la page du projet, quel que soit l’onglet ouvert : le processus, pourquoi il s’est arrêté et les dernières lignes qu’il a écrites.

• Réparer le relance, avec ceux dont il dépend, sans toucher aux autres processus.
• Ouvrir le terminal montre tout son journal.
• Ignorer masque la bannière jusqu’au prochain échec.

Quand un processus est prêt

Un serveur de dev avec un port est en ligne quand il répond à une requête HTTP, pas seulement quand son port accepte les connexions : Joppa demande GET / sur son port, et n’importe quelle réponse compte, même une 404 ou une 500. Le terminal note le moment : « prêt en 1.2 s (GET / → 200) ». Les processus qui l’attendent (« attend … », dependsOn) ne démarrent qu’après.

La colonne Prêt quand de l’analyse (le champ probe de joppa.toml) change ce que Joppa demande :

Valeur	Prêt quand
(vide)	GET / reçoit une réponse
/health, /up…	Ce chemin reçoit une réponse
tcp	Le port accepte les connexions

Si le port accepte les connexions sans qu’aucune réponse HTTP n’arrive pendant 30 secondes, ou s’il répond dans un autre protocole, Joppa le considère prêt quand même. Une fois prêt, Joppa ne lui redemande plus rien : il vérifie seulement que le port répond toujours. Les services Docker Compose sont prêts quand leur healthcheck passe, ou quand leur port répond s’ils n’en ont pas.

Mise en veille

Avec beaucoup de worktrees ouverts, chacun avec ses serveurs de dev, la mémoire part vite. Joppa met en veille les serveurs de dev d’un projet que personne n’utilise : après 15 minutes sans requête vers ses domaines, il les arrête et les marque en veille.

La requête suivante vers l’un de ses domaines les réveille :

1. le proxy garde la requête ;
2. Joppa relance les serveurs de dev mis en veille, avec ceux dont ils dépendent ;
3. dès que le serveur du domaine est prêt, la requête lui est transmise.

Une page qui attendrait plus de 3 secondes affiche « Réveil de web… », qui se recharge toute seule chaque seconde jusqu’à ce que le serveur réponde. Les autres requêtes (fetch, fichiers, WebSocket du HMR) attendent jusqu’à 90 secondes. Le HMR de Vite se reconnecte de lui-même après le réveil.

L’interrupteur Mettre en veille après … sans requête de l’onglet Processus règle le délai (de 5 min à 2 h) ou désactive la veille, projet par projet. Elle est activée par défaut pour les environnements de worktrees, désactivée pour les autres projets. C’est une préférence de votre machine, jamais écrite dans joppa.toml.

• Seuls les serveurs de dev sont mis en veille : les conteneurs Docker Compose et les services Joppa continuent de tourner.
• Joppa ne met pas en veille un projet dont un processus démarre, se relance ou exécute une action, ni un projet dont aucun domaine ne mène à un serveur de dev (aucune requête ne pourrait le réveiller), ni quand le proxy est arrêté.
• Un onglet resté ouvert sans activité n’empêche pas la veille : quand vous y revenez, le client HMR se reconnecte et réveille le serveur.
• ▶ réveille aussi un processus en veille ; ■ Tout arrêter le sort de la veille : une requête ne le relance plus.

L’état en veille apparaît dans l’onglet, dans la colonne d’état des domaines, dans le terminal et sur le compteur du projet (un z bleu, et « 4 en veille » dans la barre d’état). L’outil MCP list_processes le renvoie comme asleep.

Actions

Une action est une commande ponctuelle attachée à un processus : migrate → php artisan migrate, seed → php artisan db:seed, test → bun test. Elle se lance d’un clic, à côté du nom du processus dans l’onglet Processus ou dans la barre du terminal ouvert sur ce processus. Sa sortie s’écrit dans le terminal du processus, entre « ▶ migrate $ php artisan migrate » et « migrate : terminé » (ou « migrate : échec (code 1) »).

• Elle tourne dans le dossier du processus, avec ses variables d’environnement, que le processus soit lancé ou non.
• Un second clic pendant qu’elle tourne l’arrête.
• Une même action ne tourne qu’une fois à la fois.

Les actions se déclarent dans l’analyse (Revoir l’analyse) : + action sous la commande d’un serveur de dev, puis un nom et une commande. Joppa suggère migrate, seed et test pour Laravel, test et lint pour un projet JavaScript. Elles sont écrites dans joppa.toml quand le projet en a un. Un assistant les lance avec l’outil run_process_action du serveur MCP.

Le terminal intégré

⌘ J ouvre le terminal en bas de la fenêtre, depuis n’importe quel écran. Replié, il montre un carré d’état par processus ; ouvert, un onglet Tous puis un onglet par processus.

• ⌕ filtrer : n’affiche que les lignes qui contiennent un texte.
• ● suivre : reste collé aux dernières lignes.
• Effacer, Agrandir / Réduire.
• Redimensionner : faites glisser le bord du haut (ou ↑ / ↓ au clavier) ; un double-clic remet la hauteur par défaut. Joppa retient la dernière hauteur.

Joppa garde les 5 000 dernières lignes de chaque processus. En cas d’échec, le terminal propose l’action utile : Libérer le port ou Relancer.