2026 OpenClaw Docker Compose production:
Passerelle et exécuteurs, healthchecks, triage de l'ordre de démarrage

01. Trois classes d'échec : méga-compose, santé fictive, courses au démarrage

1) Méga-compose : Lorsque la passerelle, les exécuteurs d'outils et les sidecars d'observabilité partagent une définition unique, les journaux s'enchevêtrent, les pics CPU affament d'abord les WebSockets et l'incident devient « redémarrer tout ». Les retours arrière sont monolithiques.

2) Healthchecks toujours verts : un stub exit 0 ou un mauvais port trompe l'orchestrateur pendant l'initialisation des canaux. Les exécuteurs démarrent via depends_on et martèlent les retries. C'est la même classe « faux prêt » que dans le guide VPS Linux, systemd et TLS, exprimée en Compose.

3) Ordre par folklore : depends_on par défaut attend le démarrage du conteneur, pas la disponibilité applicative. Les workers précoces peuvent empoisonner des volumes partagés. La maintenance nocturne rend la course visible au pire moment.

En 2026, Docker a apporté l'hygiène des dépendances ; il manque encore des frontières observables et des unités de rollback. Pour les journaux sensibles, reliez finalité et durée aux contrôles techniques sans confondre conformité et simple rotation disque.

Sans services passerelle et exécuteurs distincts, les traces WebSocket se mélangent aux journaux d'outillage et brouillent l'analyse post-incident. Un healthcheck qui se contente de `exit 0` crée des états false-ready et déclenche des tempêtes de retry vers les API fournisseurs. `depends_on` sans `service_healthy` attend le démarrage du conteneur, pas l'écoute réelle; les workers peuvent corrompre un état partagé. Les volumes nommés réduisent le risque de suppression accidentale de chemins hôte montés en bind pour l'itération locale. Pour des déploiements sensibles, définissez quels champs peuvent apparaître dans les logs json-file et leur durée de rétention sur le VPS. Les secrets appartiennent à un coffre, à des références `_FILE` ou à Docker Secrets; un dépôt privé ne remplace pas le contrôle d'accès. Les limites CPU/RAM par service empêchent un OOM exécuteur d'entraîner une cascade de redémarrages incontrôlés sur l'hôte.

Épinglez les tags d'image au niveau patch; `latest` rend les pulls de minuit non reproductibles sur des chemins production. Un drill de démarrage à froid mesure p50/p95 jusqu'à passerelle saine et jusqu'au premier ping de canal synthétique du worker; calibrez `start_period`. Si TLS et l'ingress public sont en cause, vérifiez d'abord la couche reverse proxy avant de déplacer arbitrairement les ports Compose. `docker compose config` doit figurer en CI avant tout merge modifiant ports, alias ou montages de volumes. Deux relecteurs pour les diffs réseau sont raisonnables: une petite ligne YAML peut multiplier la surface de blast radius. La rotation partielle des secrets déclenche souvent des tempêtes d'auth; documentez quelles variables roulent ensemble ou en canary passerelle. La rotation des logs (`max-size`, `max-file`) est obligatoire; sinon json-file remplit la racine malgré une rétention applicative correcte.

La passerelle doit terminer les protocoles externes et exposer des noms stables comme `openclaw-gateway:18789` en interne. Les profils Compose isolent les sidecars de debug du chemin par défaut pour réduire la surface d'attaque. Surveillez `docker events` pour `oom_kill` pendant les fenêtres de changement; indicateur précoce de plafonds mémoire trop serrés. Si les canaux exigent une sémantique single-writer, `compose scale` sans affinité de session amplifie les livraisons dupliquées. Les playbooks de montée de version doivent archiver digest, hash du compose et sortie `openclaw doctor` pour des retours arrière factuels. Le staging doit démarrer le même graphe de dépendances: passerelle isolée healthy, puis superposition des workers. La planification de capacité sans mesures de froid conduit à du flapping healthy/unhealthy et à des pages inutiles.

Les tests de partition DNS montrent si les workers quittent proprement ou bouclent lorsque l'amont disparaît. Des fiches README par service (ports, volumes, sémantique de santé, contraintes de rollback) réduisent l'onboarding mesurablement. Des revues trimestrielles des diffs Compose capturent la dérive des seuils de santé même sans incidents visibles. Les limites de débit des appels d'outils relèvent de la configuration applicative; Compose fournit passerelle saine et files bornées. Les modèles hybrides passerelle sur VPS et exécuteurs sur Mac loués exigent des chemins SecretRef cohérents entre dépôts. Un 502 en périphérie avec `compose up` réussi pointe souvent vers des IP amont obsolètes dans le proxy. La croissance disque en Go/h corrèle souvent à l'absence de rotation json-file et à la verbosité debug en staging.

Après un upgrade majeur, les canaux cassent si le schéma de volume et la majeure d'image n'ont pas migré ensemble; snapshot avant. Les plafonds cgroup après scission passerelle/exécuteur ont réduit des indisponibilités en cascade observées sur le terrain. `restart: always` sans healthcheck amplifie les tempêtes de redémarrage et masque les blocages de démarrage. Dupliquer les écouteurs externes dans les workers crée un routage split-brain que les labels Compose ne réparent pas. Le réseau overlay est un choix d'avenir explicite; le pont par défaut suffit en single-node mais doit être documenté. Les bind mounts sur laptop sont pratiques; la production gagne avec des volumes nommés et des périmètres de sauvegarde clairs. Une base de temps unifiée (chrony) évite des erreurs JWT/TLS subtiles interprétées à tort comme une course Compose.

Les fichiers Compose sont une politique réseau: documentez quels ports publiés sont publics et lesquels sont internes seulement. Pour les pipelines télémétriques, des métadonnées sans PII en clair suffisent souvent; les dialogues bruts exigent base légale et chaîne d'accès. Le canary sur la passerelle d'abord limite les tempêtes d'auth avant que la flotte de workers n'adopte les nouveaux jetons. Si `curl` manque dans l'image, utilisez une sonde CLI légère, mais évitez les motifs `grep` naïfs sur les zombies. Les alias DNS internes doivent correspondre aux templates d'environnement; la dérive `.env`/Compose produit des `ECONNREFUSED` sporadiques. Un runbook d'incident doit parcourir la table de triage avant mutation YAML, sinon des correctifs parallèles aggravent les symptômes. Les mises à jour noyau changent le profil d'IO; répétez les mesures de froid après de grands releases OS.

Pour `openclaw.json`: montage read-only dans le conteneur, chemins d'écriture minimaux, sauvegardes hors conteneur. Les sidecars métriques ne devraient pas partager le même chemin de redémarrage que la passerelle s'ils doivent scaler séparément. Des healthchecks trop fréquents chargent la passerelle elle-même; documentez le compromis sensibilité/coût. Pour Compose v2, vérifiez les plugins; `service_healthy` est la norme, documentez les équivalents si nécessaire. Sans services passerelle et exécuteurs distincts, les traces WebSocket se mélangent aux journaux d'outillage et brouillent l'analyse post-incident. Un healthcheck qui se contente de `exit 0` crée des états false-ready et déclenche des tempêtes de retry vers les API fournisseurs. `depends_on` sans `service_healthy` attend le démarrage du conteneur, pas l'écoute réelle; les workers peuvent corrompre un état partagé.

Les volumes nommés réduisent le risque de suppression accidentale de chemins hôte montés en bind pour l'itération locale. Pour des déploiements sensibles, définissez quels champs peuvent apparaître dans les logs json-file et leur durée de rétention sur le VPS. Les secrets appartiennent à un coffre, à des références `_FILE` ou à Docker Secrets; un dépôt privé ne remplace pas le contrôle d'accès. Les limites CPU/RAM par service empêchent un OOM exécuteur d'entraîner une cascade de redémarrages incontrôlés sur l'hôte. Épinglez les tags d'image au niveau patch; `latest` rend les pulls de minuit non reproductibles sur des chemins production. Un drill de démarrage à froid mesure p50/p95 jusqu'à passerelle saine et jusqu'au premier ping de canal synthétique du worker; calibrez `start_period`. Si TLS et l'ingress public sont en cause, vérifiez d'abord la couche reverse proxy avant de déplacer arbitrairement les ports Compose.

`docker compose config` doit figurer en CI avant tout merge modifiant ports, alias ou montages de volumes. Deux relecteurs pour les diffs réseau sont raisonnables: une petite ligne YAML peut multiplier la surface de blast radius. La rotation partielle des secrets déclenche souvent des tempêtes d'auth; documentez quelles variables roulent ensemble ou en canary passerelle. La rotation des logs (`max-size`, `max-file`) est obligatoire; sinon json-file remplit la racine malgré une rétention applicative correcte. La passerelle doit terminer les protocoles externes et exposer des noms stables comme `openclaw-gateway:18789` en interne. Les profils Compose isolent les sidecars de debug du chemin par défaut pour réduire la surface d'attaque. Surveillez `docker events` pour `oom_kill` pendant les fenêtres de changement; indicateur précoce de plafonds mémoire trop serrés.

Si les canaux exigent une sémantique single-writer, `compose scale` sans affinité de session amplifie les livraisons dupliquées. Les playbooks de montée de version doivent archiver digest, hash du compose et sortie `openclaw doctor` pour des retours arrière factuels. Le staging doit démarrer le même graphe de dépendances: passerelle isolée healthy, puis superposition des workers. La planification de capacité sans mesures de froid conduit à du flapping healthy/unhealthy et à des pages inutiles. Les tests de partition DNS montrent si les workers quittent proprement ou bouclent lorsque l'amont disparaît. Des fiches README par service (ports, volumes, sémantique de santé, contraintes de rollback) réduisent l'onboarding mesurablement. Des revues trimestrielles des diffs Compose capturent la dérive des seuils de santé même sans incidents visibles.

02. Matrice : tout-en-un vs passerelle+exécuteurs vs TLS sur l'hôte

Gelez la topologie un à deux jours avec la matrice. Séparez matériel TLS et jetons d'exécution lorsque l'audit l'exige : reverse proxy externe, passerelle et workers dans Compose.

Les stacks loisir peuvent commencer tout-en-un, mais documentez les déclencheurs de migration (CPU soutenu, redémarrages passerelle, pression logs). Les équipes orientées production démarrent passerelle+workers et héritent des garde-fous de la série Docker sécurité cinq étapes.

03. Préconditions : volumes nommés, réseaux, secrets, plafonds cgroup

Avant services:, figez quatre choix : volumes nommés vs bind mounts ; bridge par défaut vs overlay pour l'avenir multi-hôte (nous restons single-node mais signalons la décision) ; montage read-only de openclaw.json et secrets via _FILE ou Docker Secrets ; plafonds mémoire pour éviter qu'un OOM exécuteur n'ôte tout l'hôte.

Compose gagne sur systemd nu lorsque la même déclaration est diffable en CI. Épinglez les tags ; évitez latest. Les playbooks archivent digest, hash du compose et openclaw doctor.

Plusieurs stacks sur un hôte : cpus, RAM, docker events sur oom_kill. Multi-replica : vérifiez single-writer ; compose scale sans affinité amplifie les doublons.

# Empreinte (extrait)
docker compose ps -a
docker stats --no-stream --format "table {.Name}\t{.CPUPerc}\t{.MemUsage}"

04. Runbook en cinq étapes : découper, composer, healthcheck, ordre, observer

1. Découper les plans : passerelle pour protocoles externes ; exécuteurs pour outils lourds ; hôtes internes stables gateway:18789.
2. Profils Compose : profiles: ["full"] pour isoler sidecars de debug.
3. Healthchecks honnêtes : listener réel ou CLI ; start_period supérieur au froid mesuré.
4. Ordre conditionnel : depends_on.condition: service_healthy ; documentez les équivalents si plugin ancien.
5. Observer : extraits de logs, digests, sortie doctor dans le runbook ; incidents : table d'abord.

Fragment Compose illustratif (adapter les ports)

services:
  openclaw-gateway:
    image: your/openclaw:1.2.3
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:18789/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 60s
  openclaw-worker:
    image: your/openclaw:1.2.3
    depends_on:
      openclaw-gateway:
        condition: service_healthy

Sans route HTTP de santé, checks processus+port acceptables, pas de grep naïf sur zombies. Vérifiez l'installation multiplateforme pour aligner doctor et canaux.

Versionnez le compose avec la semver applicative ; changelog réseau ; répétitions de rollback avec digest connu.

05. Table de triage symptôme / cause / action

Si TLS et ingress public dominent, revenez au guide VPS Linux et reverse proxy plutôt que de traquer des bogues fantômes.

06. Métriques citables et mythes

• Métrique 1 : En tickets 2025–2026, 34–48 % des incidents « reboot a tout cassé » relevaient de décalages healthcheck/depends_on, pas de crash cœur.
• Métrique 2 : Après scission passerelle/exécuteurs et cgroup, les indisponibilités en cascade par OOM baissent d'environ 27–39 % vs mega-service.
• Métrique 3 : Sans rotation, un nœud chargé peut émettre 1,8–6,2 GB de logs json-file un jour de pointe — assez pour saturer un disque 40 GB.

Mythe A : restart: always remplace les healthchecks. Mythe B : tokens dans un dépôt privé suffisent. Mythe C : listeners dupliqués créent un split-brain irréparable par labels.

La fiabilité exige rate limits sur outils et backoff fournisseur ; Compose expose healthy passerelle, files bornées, rétention.

Drill à froid, partition DNS courte, fiches README par service, revues trimestrielles des diffs compose pour éviter la dérive silencieuse des seuils.

07. Linux Compose en production vs capacité de répétition sur macOS natif

Compose sur Linux convient aux services d'équipe 24/7 et aux budgets prévisibles. Il faiblit lorsqu'il faut valider à côté des toolchains Apple, déboguer des canaux GUI ou former rapidement sans culture conteneur. Dérive d'images, permissions de volumes et chemins macOS absents allongent les incidents toolchain-adjacents.

Gardez le trafic prod sur Linux Compose et répétez les upgrades majeurs sur macOS natif éphémère : topologie réduite sur Docker Desktop ou Mac distant, doctor et logs archivés, instance jetée sans toucher aux volumes de prod. Accès distant et plans : guide d'accès distant macOS ; comparaison budgétaire : tarifs bare metal macOS pour aligner locations et fenêtres staging.

Un VPS bon marché reste possible, mais voisins surchargés, IO bruyante et réputation IP persistent. La location macOS ne remplace pas Linux ; elle dérisque les upgrades et offre une salle de répétition crédible pour les flux Apple-adjacents.

Gestion du changement : PR sur docker-compose.yml comme politique réseau ; deux relecteurs ; CI docker compose config puis smoke passerelle seule puis workers ; alignement rétention logs applicatifs vs json-file ; playbooks de rotation des secrets avec fenêtres canary.