Docker Desktop sur Mac distant requiert officiellement au moins 4 Go de mémoire vive, mais cette condition matérielle ne garantit ni le démarrage du backend ni la disponibilité du Docker Socket. La documentation d’installation de Docker confirme ce seuil ; en pratique, vous devez d’abord identifier la couche en panne, puis seulement envisager une réparation ou une réinstallation.
Symptôme → solution la plus rapide
- La commande
dockerest introuvable → vérifiez le chemin du CLI et lePATHde l’utilisateur SSH. - Docker Desktop est arrêté → utilisez
docker desktop status, puisdocker desktop startavec le même compte macOS. - Le client ne trouve pas le daemon → contrôlez le contexte actif, le chemin du Socket et la session qui a lancé Docker Desktop.
- Le conteneur démarre mais reste inaccessible → séparez le problème du backend Docker de celui du réseau, du port publié ou du registre.
Commencez par isoler la couche fautive
Une connexion SSH réussie ne prouve que la disponibilité de Remote Login et d’une session shell distante. Apple distingue cette session de la session de console qui contient Finder, Dock et les applications graphiques ; les deux contextes ne disposent pas automatiquement des mêmes processus ni des mêmes services utilisateur. La documentation Apple sur les contextes de session décrit cette séparation.
Lancez d’abord les commandes suivantes, sans sudo :
whoami
echo "$HOME"
command -v docker
docker version
docker context ls
docker context show
docker desktop statusInterprétez les résultats dans cet ordre :
command -v dockerne renvoie rien : le problème concerne le CLI ou lePATH, pas encore Docker Desktop.docker desktop statusindique que l’application est arrêtée : examinez la session et les journaux avant de toucher au Socket.- Docker répond que le daemon est inaccessible : comparez le contexte actif, l’utilisateur courant et le chemin du Socket.
docker versionaffiche la partie cliente mais pas la partie serveur : le CLI fonctionne, tandis que le backend n’est pas prêt.- Le backend répond, mais
curl, un navigateur ou un service externe ne joint pas le conteneur : vous êtes probablement face à un problème de publication de port, de pare-feu, de proxy ou de service applicatif.
start, stop, restart, status, logs et diagnose. [La référence officielle du CLI Docker Desktop](https://docs.docker.com/desktop/features/desktop-cli/) doit rester votre source de vérité lorsque la syntaxe évolue.
**Attention.** Une erreur « permission denied » ne signifie pas automatiquement que le compte SSH doit devenir administrateur. Docker Desktop fonctionne principalement comme utilisateur non privilégié ; seules certaines fonctions, comme les liens système, les ports inférieurs à 1 024 ou le composant auxiliaire, nécessitent une autorisation supplémentaire. [Docker détaille ce modèle de permissions sur macOS](https://docs.docker.com/desktop/setup/install/mac-permission-requirements/).
Vérifiez l’installation avant de réparer l’environnement
Avant de réinstaller, confirmez que l’application correspond à l’architecture et à la version de macOS du nœud :
uname -m
sw_vers
ls -ld /Applications/Docker.app
ls -l /Applications/Docker.app/Contents/Resources/bin/dockerUn Mac Apple Silicon renvoie généralement une architecture arm64, tandis qu’un ancien Mac Intel renvoie x86_64. Cette information ne suffit toutefois pas à conclure à une incompatibilité : il faut la comparer aux exigences publiées pour la version de Docker Desktop installée. Docker indique que la prise en charge couvre la version actuelle de macOS et les deux versions majeures précédentes, avec un minimum de 4 Go de mémoire vive. Consultez les exigences officielles actualisées plutôt que de reprendre une ancienne fiche technique.
Vérifiez ensuite le chemin du CLI. Docker Desktop peut installer les outils dans /usr/local/bin ou dans $HOME/.docker/bin. Dans le second cas, le chemin utilisateur doit être ajouté au profil du shell, par exemple :
export PATH="$HOME/.docker/bin:$PATH"Ne modifiez le profil que pour l’utilisateur qui exécute réellement les tâches. Une installation faite avec un compte administrateur, puis utilisée avec un compte de service, crée facilement un environnement incohérent : le binaire existe, mais le compte SSH ne le voit pas.
Si l’application est absente, tronquée ou impossible à ouvrir depuis la session VNC, utilisez les journaux et les outils de diagnostic avant de supprimer quoi que ce soit :
docker desktop logs
docker desktop diagnoseVous pouvez également consulter les journaux macOS avec log stream ou log show. La procédure officielle de dépannage Docker Desktop pour macOS précise les méthodes de collecte et les vérifications à effectuer.
Une réinstallation devient raisonnable seulement si les preuves convergent : application réellement endommagée, fichiers manquants, mise à jour interrompue ou diagnostic indiquant un composant absent. Sauvegardez auparavant les configurations de projet, les fichiers Compose, les identifiants nécessaires et les volumes dont la conservation est indispensable.
Rétablissez la session utilisateur et l’autorisation graphique
Le réglage « démarrer Docker Desktop à la connexion » concerne une session utilisateur. Il ne transforme pas automatiquement Docker Desktop en daemon système indépendant de toute ouverture de session. Apple distingue les agents lancés dans le contexte d’un utilisateur des daemons lancés dans le contexte système ; les applications qui affichent une interface ne fonctionnent généralement pas avant la connexion graphique. Le guide Apple sur les agents et daemons explique cette différence.
Pour une première initialisation ou après une mise à jour importante, procédez ainsi :
- Ouvrez une session VNC avec le même compte macOS que celui utilisé pour les commandes SSH.
- Lancez Docker Desktop depuis
/Applications/Docker.app. - Acceptez les demandes d’autorisation affichées par macOS ou Docker Desktop.
- Attendez que l’icône Docker indique que le backend est prêt.
- Revenez à votre terminal SSH avec ce même utilisateur.
- Exécutez
docker desktop status. - Vérifiez
docker context show, puis lancez un conteneur minimal. - Fermez et rouvrez la connexion SSH afin de confirmer que le résultat ne dépend pas d’un profil temporaire.
Réparez le couple utilisateur, contexte et Docker Socket
Le cas le plus trompeur apparaît lorsque Docker Desktop est actif, mais que le client SSH ne parle pas au bon endpoint. Docker Desktop règle normalement le contexte desktop-linux au démarrage ; la documentation indique également que le CLI s’appuie sur le contexte courant pour retrouver le chemin du Socket. Les réglages macOS de Docker Desktop décrivent ce comportement ainsi que l’option permettant d’utiliser le Socket par défaut.
Comparez les variables et les chemins :
whoami
echo "$HOME"
echo "${DOCKER_HOST:-non défini}"
docker context show
docker context inspect
ls -l "$HOME/.docker/run/docker.sock"
ls -l /var/run/docker.sockSur macOS, le Socket utilisateur peut se trouver sous $HOME/.docker/run/docker.sock. Selon l’installation, Docker Desktop peut aussi créer un lien /var/run/docker.sock. Ce lien n’est pas une garantie permanente : Docker précise que /var/run est monté comme un système temporaire et que le lien doit être recréé au démarrage lorsqu’il est activé dans la configuration.
Ne faites pas ceci :
sudo touch /var/run/docker.sockUn fichier vide portant le nom attendu n’est pas un Socket fonctionnel. Il masque le diagnostic et peut provoquer des erreurs différentes selon l’outil client. Ne remplacez pas non plus le contexte par une variable DOCKER_HOST permanente sans sauvegarder l’environnement initial.
Avant toute modification :
cp -R "$HOME/.docker" "$HOME/.docker.backup.$(date +%Y%m%d-%H%M%S)"
env | grep -E '^(DOCKER|PATH)=' > "$HOME/docker-env-backup.txt"Si le contexte est incohérent, sélectionnez le contexte réellement fourni par Docker Desktop avec l’utilisateur qui exécute le travail, puis testez immédiatement :
docker context use desktop-linux
docker info
docker run --rm hello-worldSi desktop-linux n’existe pas ou si docker info échoue toujours, arrêtez-vous : le problème se situe probablement au niveau du démarrage du backend, de la session ou de l’installation, et non dans le simple choix du contexte.
Séparez permissions, registre et réseau
Trois erreurs peuvent se ressembler dans un journal :
- Docker Desktop ne démarre pas ;
- le registre privé refuse l’authentification ;
- le conteneur démarre, mais son service n’est pas joignable.
docker run --rm hello-worldPuis testez le projet réel sans lancer toute la chaîne de publication :
docker compose config
docker pull votre-registre/exemple:tag
docker run --rm -p 127.0.0.1:8080:80 votre-image:tag
curl -I http://127.0.0.1:8080Remplacez votre-registre, exemple:tag et votre-image:tag par vos valeurs ; ne placez jamais de jeton réel dans un script ou dans un article. Pour un registre privé, utilisez un mécanisme d’authentification non interactif adapté à votre gestionnaire de secrets, puis vérifiez que le compte SSH peut accéder au trousseau et aux fichiers de configuration attendus.
Un port inférieur à 1 024 peut nécessiter le composant auxiliaire privilégié de Docker Desktop. À l’inverse, une application qui écoute sur 127.0.0.1 ne sera pas nécessairement accessible depuis votre poste Windows ou Linux. Testez donc séparément l’écoute locale, la publication Docker et l’accès depuis le réseau distant.
Pour les tâches audio, vidéo ou design exécutées dans des conteneurs, ajoutez une vérification spécifique : accès aux volumes de travail, disponibilité des fichiers médias après reconnexion, variables d’environnement et durée de conservation des artefacts. Un nœud qui exécute docker run mais perd son volume de cache ou son répertoire de rendu après redémarrage n’est pas opérationnel pour une chaîne de production.
Validez le nœud avec une checklist de reprise
Utilisez cette checklist après une mise à jour, un redémarrage ou une correction de configuration :
- [ ] Le compte SSH est le même que celui qui a initialisé Docker Desktop.
- [ ]
command -v dockerrenvoie le binaire attendu. - [ ]
docker desktop statusindique un état démarré. - [ ] La session VNC a été ouverte si une autorisation graphique était nécessaire.
- [ ]
docker context showrenvoie le contexte destiné à Docker Desktop. - [ ] Le Socket indiqué par le contexte existe et appartient au bon utilisateur.
- [ ]
docker infoaffiche la partie serveur. - [ ]
docker run --rm hello-worlds’exécute sans modifier les données métier. - [ ] Une image privée peut être tirée avec le mécanisme d’authentification prévu.
- [ ] Un conteneur de test répond sur son port publié.
- [ ] Les conteneurs métier suivent une politique de redémarrage explicitement documentée.
- [ ] La procédure indique clairement si une intervention VNC reste nécessaire.
Comparez les scénarios avant de retenir une architecture
Le tableau suivant sert à décider quelle action entreprendre, et non à classer toutes les erreurs sous l’étiquette « Docker cassé ».
| Observation depuis SSH | Preuve à collecter | Action prioritaire | Score de confiance |
|---|---|---|---|
docker introuvable | command -v docker, echo $PATH | Corriger le chemin utilisateur | 2/2 |
| Application arrêtée | docker desktop status, journaux | Démarrer avec le même compte, puis vérifier VNC | 2/2 |
| Client sans daemon | docker context, DOCKER_HOST, Socket | Réaligner contexte et utilisateur | 2/2 |
| Socket absent après redémarrage | ls, réglage du Socket par défaut | Vérifier la configuration Docker, sans créer de faux fichier | 2/2 |
| Image privée refusée | docker pull, accès au trousseau | Corriger l’authentification du compte distant | 2/2 |
| Service non joignable | docker ps, curl, écoute du port | Examiner publication, proxy et réseau | 2/2 |
| Scénario | Atout principal | Limite à accepter | Adapté si… |
|---|---|---|---|
| Mac local dédié | Contrôle direct et récupération immédiate | Achat, maintenance et disponibilité physique | Vous avez un besoin permanent et une équipe sur place |
| Mac distant avec SSH et VNC | Accès à un vrai macOS depuis Windows ou Linux | La session graphique peut rester nécessaire | Vous devez développer, construire ou tester à distance |
| Mac distant utilisé en SSH-only | Automatisation simple dans les scripts | La première autorisation et la reprise doivent être prouvées | Le nœud a passé un test de redémarrage documenté |
| Machine Linux avec conteneurs | Administration souvent plus simple | Ne remplace pas les outils macOS et Xcode | Votre chaîne ne dépend d’aucun composant Apple |
Questions fréquentes
Pourquoi SSH fonctionne-t-il alors que Docker ne répond pas sur le Mac distant ?
SSH prouve uniquement que Remote Login et votre session shell sont accessibles. Docker Desktop dépend aussi d’une application utilisateur, de son backend Linux, du contexte desktop-linux et d’un Socket accessible au même compte. Connectez-vous en SSH avec l’utilisateur qui a initialisé Docker, puis vérifiez l’état de l’application, le contexte actif et le chemin du Socket avant de modifier les permissions.
Docker Desktop peut-il démarrer sans interface graphique sur un Mac distant ?
Vous pouvez lancer certaines commandes depuis SSH avec docker desktop start, status, restart ou logs. Toutefois, la première initialisation, l’autorisation des composants privilégiés et certaines migrations de configuration peuvent nécessiter la session VNC du même utilisateur. Ne considérez donc pas un scénario SSH-only comme garanti tant que la reprise après redémarrage n’a pas été testée sur votre nœud.
Que faire si le Docker Socket disparaît après le redémarrage du Mac ?
Ne créez pas un fichier Socket vide et ne copiez pas aveuglément un lien trouvé sur un forum. Docker Desktop utilise généralement un Socket dans le répertoire utilisateur et peut créer /var/run/docker.sock via une option d’installation dédiée. Vérifiez d’abord le contexte actif, l’utilisateur, le chemin réellement indiqué par Docker et l’option de Socket par défaut, puis sauvegardez toute configuration avant correction.
Comment savoir si Docker Desktop est fiable pour un nœud distant permanent ?
Réalisez un test de reprise complet : redémarrage du Mac, retour SSH, ouverture éventuelle de la session VNC, état Docker Desktop, contexte desktop-linux, disponibilité du Socket, exécution d’un conteneur minimal et récupération des conteneurs métier. Répétez le scénario selon votre politique d’exploitation. Si une intervention graphique reste nécessaire, documentez-la comme une dépendance et non comme une anomalie ponctuelle.
Décidez si votre environnement est prêt pour la production
La bonne question n’est pas seulement de savoir si Docker Desktop démarre aujourd’hui. Vous devez vérifier si le nœud revient dans un état exploitable après une coupure, si le même utilisateur retrouve le bon contexte, si le Socket est recréé correctement et si vos conteneurs peuvent reprendre sans intervention imprévue.
Votre environnement actuel peut convenir si vous acceptez une étape VNC documentée, si les redémarrages sont planifiés et si les secrets, volumes et politiques de reprise sont maîtrisés. Il devient moins adapté lorsque la chaîne exige une disponibilité totalement indépendante de toute session utilisateur, une reprise automatique après chaque panne ou une administration homogène de nombreux nœuds.
Dans ce dernier cas, un Mac distant fourni avec accès VNC, SSH et une procédure de reprise vérifiable peut être plus cohérent qu’un poste local bricolé ou qu’une machine Linux qui ne fournit pas les outils macOS nécessaires. Vous pouvez comparer les solutions de Mac distant pour le développement et examiner les configurations Mac Apple Silicon disponibles avant de décider entre réparation, achat d’un Mac mini ou location temporaire.
Si votre objectif est de valider une chaîne Docker, un nœud de compilation ou un environnement de test sans immobiliser immédiatement un Mac physique, MACGPU permet d’évaluer un véritable Mac distant avec SSH et VNC. La décision reste technique : retenez cette voie si elle réduit les opérations manuelles que votre procédure actuelle ne sait pas absorber, et non simplement parce que Docker affiche parfois une erreur au démarrage.