joppa.toml

joppa.toml décrit, à la racine d’un projet, tout ce dont il a besoin dans Joppa : ses domaines, ses services et sa base, ses versions, ce que Joppa fait de ses worktrees et ses processus. Commitez-le : un collègue qui clone le dépôt et l’ajoute à Joppa a tout prêt en un clic, après avoir validé ce que Joppa va faire.

Toutes les sections sont facultatives. Un fichier qui ne contient que des [[process]] (celui des premières versions de Joppa) reste valable.

L’écrire

Sur la page du projet, menu Actions (⋯) › Partager la configuration dans joppa.toml, ou le lien du même nom sous la liste des processus. Joppa montre le fichier tel qu’il sera écrit (et, s’il existe déjà, ce qui change), puis Écrire joppa.toml l’enregistre à la racine du dépôt. Joppa y met :

• le nom du projet ;
• ses domaines, en libellés sous ce nom (un domaine qui n’est pas sous le nom du projet est laissé de côté, et Joppa le dit) ;
• les services liés, avec leur version, leur base et les extensions de cette base ;
• ce que Joppa fait des worktrees, s’il a été réglé ;
• les processus.

La section [runtime] et les sections que cette version de Joppa ne connaît pas sont gardées telles quelles. Vous pouvez aussi écrire le fichier à la main.

Cocher Écrire joppa.toml dans le dépôt pour l’équipe dans l’analyse des processus n’écrit que les [[process]] : les autres sections du fichier ne bougent pas.

Exemple

[project]
name = "acme"

# app.acme.test → le processus web ; acme.test → le port 49100
[[domain]]
label = "app"
process = "web"

[[domain]]
label = ""
port = 49100

[[service]]
engine = "postgres"
version = "17"
extensions = ["postgis", "vector"]
database = "acme"

[[service]]
engine = "redis"
env = false

[runtime]
node = "22"
packageManager = "[email protected]"

[worktrees]
auto = true
database = "empty"

[[process]]
name = "postgres"
kind = "compose"
service = "db"

[[process]]
name = "api"
kind = "script"
dir = "apps/api"
command = "pnpm run dev"
port = 8000
dependsOn = ["postgres"]
probe = "/health"

[process.env]
PORT = "8000"

[[process.actions]]
name = "migrate"
command = "pnpm run db:migrate"

[[process.actions]]
name = "test"
command = "pnpm test"

[[process]]
name = "web"
kind = "script"
dir = "apps/web"
command = "pnpm run dev"
port = 48100
dependsOn = ["api"]

[[process]]
name = "worker"
kind = "script"
command = "bun run queue"
enabled = false

[project]

Chaque [[process]] est un processus.

Champ	Type	Rôle
name	texte	Nom unique dans le projet : web, api, postgres
kind	"script" ou "compose"	Une commande, ou un service du Docker Compose du projet
port	nombre	Le port sur lequel il répond une fois prêt. Absent pour une tâche de fond
dependsOn	liste	Processus démarrés (et prêts) avant celui-ci
enabled	booléen	Lancé par « Tout démarrer » (true par défaut). À false, il se lance seul
probe	texte	Serveur de dev : comment Joppa sait qu’il est prêt. Un chemin HTTP ("/health" ; / par défaut) ou "tcp". Voir Quand un processus est prêt
actions	liste	Commandes ponctuelles proposées à côté du processus : [[process.actions]] avec name et command. Voir Actions

kind = "script"

Champ	Rôle
command	La commande, lancée dans un shell
dir	Le dossier, relatif à la racine du projet (vide : la racine)
env	Variables d’environnement ajoutées ([process.env])

kind = "compose"

Champ	Rôle
service	Le nom du service dans le fichier Docker Compose

Quand le fichier existe, ses processus font foi sur la configuration locale.

Appliquer le fichier

Joppa n’applique jamais joppa.toml sans vous. Il montre d’abord un plan, étape par étape, que vous validez :

• À l’ajout du projet : la fenêtre Ajouter un projet remplit le nom et les domaines d’après le fichier, et liste sous Configuration d’équipe · joppa.toml le reste : créer ou réutiliser le serveur, créer la base avec ses extensions, lier le projet, écrire le .env, épingler les versions, régler les worktrees. Ajouter et préparer fait les étapes cochées.
• Après un git pull qui modifie le fichier : la page du projet affiche « joppa.toml a changé », avec ce qui a changé depuis la dernière application sur cette machine. Voir ouvre le plan ; Appliquer fait les étapes cochées ; Ignorer cette version le laisse tel quel jusqu’au prochain changement.

Le plan :

• ne détruit rien : une base qui existe est réutilisée, les extensions sont seulement ajoutées, le .env est écrit avec son diff (et une copie de l’ancien), un domaine déjà pris par un autre projet n’est pas touché ;
• respecte la licence : un moteur réservé à Joppa Pro n’est pas créé en version gratuite, l’étape le dit ;
• ne lance aucun processus : les processus d’un joppa.toml qui arrive avec un git pull gardent leur approbation (ci-dessous).

Chaque étape est vérifiée au moment de l’appliquer : si le fichier ou le .env a changé entre-temps, elle n’est pas faite et Joppa demande de rouvrir le plan.

Les processus d’un fichier qui a changé

Un joppa.toml arrive avec git pull : ses commandes peuvent avoir changé. Lancer à l’ouverture de Joppa ne lance que les commandes que cette machine a déjà lancées ou enregistrées ; après un changement, les processus attendent que vous les démarriez une fois à la main.

Ce qui n’y est pas

Lancer à l’ouverture de Joppa, Relancer après un plantage et Mettre en veille après … sans requête sont des préférences de chaque machine : elles restent dans Joppa et ne sont jamais écrites dans joppa.toml.