Démarrer une stack Docker Compose avec vérification d'état

Vous voulez que Runyard lance votre stack backend via docker compose up, qu'il la considère en cours seulement lorsque votre API répond, et qu'il arrête tout proprement quand vous cliquez sur Stop.

Le piège

Deux pièges classiques.

1. Deux CLI, même nom. docker compose (le plugin V2, en deux mots) est la syntaxe actuelle. Le binaire autonome docker-compose (avec un trait d'union) est l'ancienne version, de plus en plus absente sur les installations récentes. Utilisez le plugin V2.
2. SIGTERM ne nettoie pas. L'arrêt par défaut de Runyard envoie SIGTERM à docker compose up, puis SIGKILL après un délai de grâce. Cela arrête le processus compose au premier plan, mais laisse vos conteneurs tourner en arrière-plan. Il faut une entrée stopCommands explicite qui exécute docker compose down pour démonter les conteneurs, les réseaux et les volumes proprement.

Configuration qui fonctionne

{
  "name": "Backend Stack",
  "type": "service",
  "directory": "~/Code/votre-projet",
  "autoStart": false,
  "startCommands": [{
    "label": "Compose",
    "command": "docker",
    "args": ["compose", "up"],
    "startupCheck": "http://localhost/api/health",
    "startupFallbackPort": 8000,
    "startupRequestTimeout": 30
  }],
  "stopCommands": [{
    "label": "Compose down",
    "command": "docker",
    "args": ["compose", "down"]
  }],
  "paths": ["/opt/homebrew/bin", "/Applications/Docker.app/Contents/Resources/bin"]
}

Remplacez directory, le chemin de l'URL de santé et le port de repli par vos propres valeurs.

Pourquoi ça fonctionne

• docker compose up (sans -d) garde Compose attaché à votre terminal. Runyard suit son PID et considère le service vivant tant que Compose s'exécute.
• startupCheck interroge l'endpoint de votre API. Le port est détecté automatiquement à partir du stdout de Compose lorsqu'il affiche un message du genre Listening on 0.0.0.0:8000. Si la détection échoue (certaines versions de Compose affichent l'information de port via un sous-processus que Runyard ne peut pas tracer), startupFallbackPort prend le relais.
• startupRequestTimeout: 30 donne aux conteneurs lents (bases de données, migrations, etc.) le temps de démarrer avant que chaque tentative ne soit considérée comme un échec.
• stopCommands exécute docker compose down au lieu de s'appuyer sur SIGTERM. C'est la seule façon sûre de démonter une stack : tous les services du fichier compose sont arrêtés et le réseau par défaut est supprimé.
• Le tableau paths garantit que docker est résolu dans un shell vierge. Ajustez si vous utilisez OrbStack (/Applications/OrbStack.app/Contents/MacOS/xbin) ou Colima.

Prérequis

• Docker Desktop, OrbStack ou Colima déjà en marche. Runyard ne démarre pas le démon Docker à votre place.
• Un fichier docker-compose.yml (ou compose.yml) à la racine du répertoire de l'outil.
• Un endpoint de santé dans votre application. S'il n'y en a pas, vous pouvez utiliser une sonde TCP en remplaçant startupCheck par ce qui convient à votre stack, ou utiliser un outil healthCheck séparé.

Pièges supplémentaires

• Si votre compose.yml utilise restart: unless-stopped, les conteneurs reviennent au prochain lancement de Runyard. Mettez restart: "no" pour le dev, ou acceptez les avertissements « already running ».
• docker compose down -v (avec -v) supprime les volumes nommés. N'ajoutez pas -v à la commande d'arrêt sauf si vous voulez vraiment effacer les données à chaque fois.
• Si la détection de port échoue systématiquement, mettez startupFallbackPort au port côté hôte (partie gauche de 8000:8000 dans votre fichier compose), pas au port côté conteneur.