Docker Compose sur puce Apple : images amd64, Rosetta et contrôles de santé

arm64 en priorité, amd64 si nécessaire

Un Mac de la série M exécute les conteneurs Linux sur un noyau Linux arm64. Lorsque vous téléchargez une image multiarchitecture (postgres, redis, node, python et la plupart des images officielles), Docker choisit automatiquement la variante arm64, qui s'exécute à vitesse native.

Certaines images ne sont encore distribuées que pour amd64 : anciennes images internes, outils de fournisseurs et tout ce qui est construit sur un ordinateur Intel ou un runner CI sans option de plateforme. Pour celles-ci, indiquez-le explicitement :

services:
  legacy-tool:
    image: example/amd64-only-tool:1.4
    platform: linux/amd64

Oxcart exécute les images amd64 via Rosetta, la traduction x86-64 d'Apple, et Buildx peut construire et charger des images amd64 que le moteur exécute ensuite localement. Vérifiez l'architecture réellement utilisée par un conteneur avec docker run --rm --platform linux/amd64 alpine uname -m, qui affiche x86_64.

Un exemple complet

Une base de données Postgres, une API construite depuis le dossier courant qui attend que la base soit saine, et un outil disponible uniquement pour amd64 activé par un profil :

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: dev
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      timeout: 3s
      retries: 15

  api:
    build: .
    init: true
    environment:
      DATABASE_URL: postgres://postgres:dev@db:5432/postgres
    ports:
      - "127.0.0.1:8080:8080"
    depends_on:
      db:
        condition: service_healthy

  legacy-tool:
    image: example/amd64-only-tool:1.4
    platform: linux/amd64
    profiles: ["tools"]

volumes:
  pgdata:

Le rôle de chaque partie :

• healthcheck indique à Compose quand Postgres accepte réellement les connexions, et pas seulement quand il a démarré.
• depends_on: condition: service_healthy fait attendre l'API jusqu'à la réussite de ce contrôle.
• init: true exécute un petit init comme PID 1 pour que les signaux atteignent votre processus et que les processus zombies soient récupérés. docker stop se termine alors proprement au lieu d'attendre l'expiration du délai.
• 127.0.0.1:8080:8080 publie l'API uniquement sur la boucle locale de votre Mac. Sans adresse, un port publié écoute sur toutes les adresses IPv4 du Mac et les autres machines de votre réseau peuvent l'atteindre.
• pgdata est un volume nommé : les données survivent à docker compose down et ne sont supprimées que par down -v.

Exécuter une stack Compose sur puce Apple

1. Vérifiez les outils. Exécutez docker compose version et docker context show. Oxcart inclut Docker Compose 5.6.0 avec la CLI docker 29.9.0 et Buildx 0.38.0, et son contexte s'appelle oxcart.
2. Écrivez le fichier Compose. Donnez un healthcheck à chaque service dont votre application attend la disponibilité et faites patienter les services dépendants avec depends_on: condition: service_healthy.
3. Démarrez et attendez un état sain. Exécutez docker compose up -d --build --wait. La commande se termine une fois que chaque service fonctionne et est sain, ou échoue si l'un d'eux ne l'est pas.
4. Vérifiez les ports. Exécutez docker compose ps ou ouvrez la vue Ports d'Oxcart, qui indique pour chaque port publié s'il est prêt, en attente ou en échec, avec le motif.
5. Itérez. Modifiez le code et exécutez docker compose up -d --build api. Les étapes de construction inchangées proviennent du cache.
6. Arrêtez et supprimez les conteneurs. Exécutez docker compose down pour arrêter et supprimer les conteneurs, ou docker compose down -v pour supprimer également les volumes nommés.

Des reconstructions plus rapides

Compose construit via Buildx et BuildKit. Organisez votre Dockerfile pour installer les dépendances avant COPY . . : une modification du code réutilise alors toutes les couches en cache qui précèdent. Dans Oxcart, la construction du projet de benchmark a pris 121 ms avec cache et 341 ms sans cache avec un contexte local : les meilleurs résultats des trois environnements testés dans les deux cas. Les cycles courts s'additionnent : docker run --rm a pris 42 ms, et l'arrêt puis la suppression de 20 conteneurs 77 ms.

Oxcart 0.1.2 mesuré le 2026-10-10 avec son client docker 29.9 inclus ; les autres environnements mesurés plus tôt le même jour, sur le même Mac et avec le même dispositif de mesure, avec docker 29.4. Apple M5 Max, 8 CPU et 12 GiB chacun, un environnement à la fois.

Les ports, le Mac et les autres services

• La syntaxe des ports est celle de Docker : TCP et UDP, ports éphémères ("127.0.0.1::8080") et "[::]:8080:80" pour écouter en IPv4 et IPv6. TCP et UDP peuvent partager un numéro de port hôte.
• Le Mac depuis un conteneur : host.docker.internal atteint en TCP les services liés à l'adresse 127.0.0.1 du Mac, depuis les conteneurs et les étapes de construction.
• Un registre local : publiez un conteneur de registre sur le port 5000, et docker push localhost:5000/app l'atteint.
• Sidecars : network_mode: service:api place un conteneur dans l'espace de noms réseau d'un autre service, pour partager son localhost.

Pour les VPN, le DNS, les pare-feu et la protection du chemin réseau, voir Réseau des conteneurs sur Mac.

Volumes nommés et bind mounts

Utilisez des volumes nommés pour les données très sollicitées en écriture par la base de données ou la construction : node_modules, caches de paquets, fichiers de base de données. Leurs données restent dans le stockage du moteur. Dans Oxcart, un volume nommé a effectué 1,000 opérations de création, stat, lecture et suppression de petits fichiers en 17.8 ms, le meilleur résultat des trois environnements testés.

Utilisez des bind mounts pour le code source que vous modifiez sur votre Mac. Par défaut, Oxcart partage votre dossier personnel, /private/tmp et /private/var/folders avec les conteneurs en lecture-écriture : les modifications sur le Mac apparaissent dans les conteneurs, et celles faites dans les conteneurs apparaissent sur le Mac. Une limite à connaître : les modifications de fichiers faites sur le Mac ne produisent pas d'événements inotify dans les conteneurs. Un outil de surveillance des fichiers dans un conteneur doit donc utiliser des interrogations périodiques pour détecter les modifications de votre éditeur.

Dépannage

Questions

Docker Compose fonctionne-t-il sur les Mac à puce Apple ?

Oui. Compose fonctionne nativement sur arm64 et la plupart des images officielles proposent des variantes arm64. Oxcart inclut Docker Compose 5.6.0, et ses vérifications de compatibilité couvrent les services multiples, les dépendances basées sur les contrôles de santé, up --wait, build, down, le DNS par nom de service, init: true et network_mode: service:.

Comment exécuter une image amd64 (x86-64) sur un Mac de la série M ?

Définissez platform: linux/amd64 sur le service, ou passez --platform linux/amd64 à docker run. Oxcart exécute les images amd64 via Rosetta. Préférez une image arm64 native lorsqu'elle existe ; utilisez amd64 pour les images sans version arm64.

Que signifie « exec format error » ?

Le conteneur a essayé d'exécuter un binaire construit pour une architecture CPU différente de la sienne. Généralement, une image ou un binaire qu'elle contient est uniquement pour amd64. Ajoutez platform: linux/amd64 à ce service, ou reconstruisez l'image pour arm64.

Pourquoi mon application indique-t-elle « connection refused » alors que le conteneur fonctionne ?

La cause la plus courante est un serveur qui écoute sur 127.0.0.1 dans le conteneur. Les ports publiés atteignent l'interface réseau du conteneur, pas sa boucle locale : le serveur doit donc écouter sur 0.0.0.0. La vue Ports d'Oxcart identifie explicitement ce cas.

Comment faire attendre un service jusqu'à ce qu'un autre soit prêt ?

Ajoutez un healthcheck à la dépendance et depends_on: { db: { condition: service_healthy } } au service dépendant. docker compose up --wait ne se termine alors que lorsque chaque service est sain.

Les conteneurs peuvent-ils atteindre un serveur qui fonctionne sur mon Mac ?

Oui. Utilisez host.docker.internal : dans Oxcart, il atteint en TCP les services liés à l'adresse 127.0.0.1 du Mac, depuis les conteneurs et les constructions.

Faut-il utiliser des volumes nommés ou des bind mounts pour les bases de données ?

Utilisez un volume nommé pour les données de la base : il réside dans le stockage propre au moteur. Utilisez des bind mounts pour le code source que vous modifiez sur le Mac. Dans Oxcart, un volume nommé a effectué 1,000 opérations de création, stat, lecture et suppression de petits fichiers en 17.8 ms.

Sources et méthode

• Compatibilité : intégrations vérifiées d'Oxcart (CLI docker, Compose avec dépendances basées sur les contrôles de santé, up --wait, init: true, network_mode: service:, Buildx, amd64 via Rosetta).
• Chiffres de vitesse : Oxcart 0.1.2, 2026-10-10, Apple M5 Max, 8 CPU et 12 GiB, médianes de cinq échantillons après échauffement ; les autres environnements ont été mesurés plus tôt le même jour sur le même Mac et avec le même dispositif de mesure, avec le client docker 29.4.
• Outils inclus : docker 29.9.0, Docker Compose 5.6.0, Buildx 0.38.0.