Docker-out-of-Docker aka DooD

Dans des situations très exceptionnelles, vous pourriez avoir besoin de lancer des commandes Docker depuis un container Docker. Attendez ? Quoi ?

Imaginez la situation suivante : vous faites tourner un container PHP, tout va bien, et vous voulez lancer un outil de qualité de code comme, commençons simple, phplint (voir cet article pour plus de détails). Vous ne voulez pas installer phplint parce que vous connaissez une image Docker très pratique qui le contient déjà (pensez à jakzal/phpqa).

Donc, vous êtes dans un container et vous voulez lancer un autre container.

Autre exemple : vous êtes toujours dans un container et vous voulez accéder à la liste des containers qui tournent, aux images Docker déjà installées, aux volumes, ... (pensez à portainer)

Voyons dans cet article comment créer votre propre image Docker, tournant en root ou pas, et la configurer pour autoriser les requêtes Docker.

L'usage réel le plus courant de cette technique est un pipeline CI dont le job doit lancer docker run ; c'est le sujet de GitLab - Exécuter Docker-out-of-Docker dans votre CI.

Nous allons utiliser la technique Docker-out-of-Docker, aussi appelée DooD : monter le socket Docker de l'host (/var/run/docker.sock) et lancer le CLI Docker dans le container.

Le résultat : des commandes Docker lancées depuis un container​

Une fois le socket Docker de l'host monté dans un container, les commandes docker lancées depuis celui-ci atteignent directement le daemon de l'host — aucune installation Docker-in-Docker nécessaire :

docker image list fonctionne aussi, depuis le container, et liste chaque image déjà présente sur l'host. La suite de cet article construit le Dockerfile et le compose.yaml qui rendent cela possible, puis montre la même astuce avec un utilisateur non-root.

Pourquoi ça marche​

• Le container ne fait jamais tourner son propre daemon Docker — il parle uniquement à celui qui tourne déjà sur l'host, via le /var/run/docker.sock partagé.
• Ce socket n'est qu'un fichier Unix : le monter dans le container suffit, pas besoin de mode privilégié ni d'une installation complète Docker-in-Docker.
• N'importe quel CLI Docker installé dans le container devient un client du daemon de l'host — docker version, docker ps, docker image list fonctionnent tous dès que le socket est là.

Installation​

Comme toujours, nous allons construire un exemple pleinement fonctionnel.

Créez un dossier bidon et placez-vous dedans : mkdir /tmp/dood && cd $_.

Il nous faut un Dockerfile, créons-le.

# syntax=docker/dockerfile:1?

FROM alpine:latest?

# hadolint ignore=DL3008?
# Note: use docker.io and not docker if you are using another image than alpine (i.e. with apt-get and not apk)?
RUN apk add --no-cache docker?

# hadolint ignore=DL3002?
USER root

Nous allons aussi utiliser un compose.yaml, créez ce fichier également :

# cspell:ignore dood
name: "dood-as-root"
services:
  dood:
    build: .?
    tty: true?
    working_dir: /src
    volumes:?
      # We need to share the Docker socket: this technique is called "Docker-out-of-Docker"
      - /var/run/docker.sock:/var/run/docker.sock?

Nous allons créer notre image Docker et un container avec cette seule commande : docker compose up --detach --build.

Et maintenant, entrons dans le container en lançant : docker compose exec dood /bin/sh.

En lançant docker version dans le container, vous obtenez la sortie montrée plus haut. Pour vérifier maintenant si vous pouvez accéder à la liste des images installées sur votre host (ce qui est en théorie impossible), lancez docker image list et ... ça marche.

Docker-out-of-Docker (DooD) est activé ; cool, mais pourquoi ?​

Pour comprendre pourquoi, rouvrez votre fichier compose.yaml et mettez l'entrée volumes en commentaire comme illustré ci-dessous :

name: "dood-as-root"
services:
  dood:
    build: .?
    tty: true?
    working_dir: /src?
    // highlight-start
    # volumes:
    #   # We need to share the Docker socket: this technique is called "Docker-out-of-Docker"
    #   - /var/run/docker.sock:/var/run/docker.sock?
    // highlight-end

Si vous êtes encore dans le container, tapez exit pour revenir à la console de votre host.

De là, reconstruisez l'image et le container en relançant docker compose up --detach --build && docker compose exec dood /bin/sh.

Une fois dans la console du container, tapez à nouveau docker version et boum.

$ docker version
Client:
 Version:           28.3.3
 API version:       1.51
 Go version:        go1.24.4
 Git commit:        980b85681696fbd95927fd8ded8f6d91bdca95b0
 Built:             Tue Jul 29 15:17:52 2025
 OS/Arch:           linux/amd64
 Context:           default
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
▋

Ça ne marche plus.

Tapez exit à nouveau, quittez le container, remettez le fichier compose.yaml comme avant (retirez les lignes commentées) et relancez docker compose up --detach --build && docker compose exec dood /bin/sh.

De retour dans la console du container, vous pouvez donc lancer des commandes comme docker ps pour obtenir la liste des containers qui tournent sur l'host et, par exemple, en arrêter certains (par ex. docker container stop 68e41eee2efd ; possible seulement si DooD est correctement configuré).

Plus de démos : faire tourner le container avec un utilisateur non privilégié​

Ça fonctionnait sans trop de difficultés parce que nous étions root. Nous avons démarré le container en root. Tapez simplement whoami dans le container pour le vérifier. Vous pouvez aussi taper id -u pour voir que votre ID utilisateur est 0 (root).

Et vous le savez, faire tourner des containers en root est une mauvaise idée. Créons donc un utilisateur spécifique.

Pour cela, nous devons mettre à jour nos fichiers.

# syntax=docker/dockerfile:1

# cspell:ignore groupid,johndoe,addgroup,adduser

ARG DOCKER_OS_GROUPID=1000?
ARG DOCKER_OS_USERID=1000?
ARG DOCKER_OS_USERNAME="johndoe"?

FROM alpine:latest

# hadolint ignore=DL3008
# Note: use docker.io and not docker if you are using another image than alpine (i.e. with apt-get and not apk)
RUN apk add --no-cache docker

ARG DOCKER_OS_GROUPID?
ARG DOCKER_OS_USERID
ARG DOCKER_OS_USERNAME

RUN set -e -x \?
    && mkdir -p "/home/${DOCKER_OS_USERNAME}" \
    && addgroup -g "${DOCKER_OS_GROUPID}" "${DOCKER_OS_USERNAME}" \?
    # Create our application user
    && adduser -S -D -u "${DOCKER_OS_USERID}"  -G "${DOCKER_OS_USERNAME}" -h "/home/${DOCKER_OS_USERNAME}" "${DOCKER_OS_USERNAME}" \?
    # And, finally, set the correct permissions to the home folder of our user
    && chown -R "${DOCKER_OS_USERNAME}":"${DOCKER_OS_GROUPID}" "/home/${DOCKER_OS_USERNAME}"

USER "${DOCKER_OS_USERNAME}"?

# cspell:ignore dood,groupid,johndoe
name: "dood-as-unprivileged"
services:
  dood:
    build:
      args:
        - DOCKER_OS_GROUPID=${DOCKER_OS_GROUPID:-1000}?
        - DOCKER_OS_USERID=${DOCKER_OS_USERID:-1000}
        - DOCKER_OS_USERNAME=${DOCKER_OS_USERNAME:-johndoe}
    user: "${DOCKER_OS_USERID:-1000}:${DOCKER_OS_GROUPID:-1000}"?
    tty: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock?

Maintenant, construisez cette nouvelle image et entrez dans le container avec, toujours la même, cette commande : docker compose up --detach --build && docker compose exec dood /bin/sh.

En tapant whoami, on voit que nous ne sommes plus root mais johndoe, avec l'ID utilisateur 1000 (id -u) et l'ID de groupe 1000 (id -g).

Comme nous partageons toujours notre /var/run/docker.sock dans le fichier yaml, on s'attend à ce que Docker-out-of-Docker fonctionne encore ; non ?

Essayons : docker ps pour obtenir la liste des containers.

$ docker ps
permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.51/containers/json": dial unix /var/run/docker.sock: connect: permission denied▋

Tout semble correct mais ... pourquoi ?

Pour pouvoir utiliser DooD avec un utilisateur non privilégié, il faut faire attention à ceci : votre utilisateur doit être membre du groupe docker de l'host. Et compose.yaml offre un moyen simple de le faire.

Mettez à jour votre compose.yaml en ajoutant les deux lignes ci-dessous.

# cspell:ignore dood,groupid,johndoe
name: "dood-as-unprivileged"
services:
  dood:
    build:
      args:
        - DOCKER_OS_GROUPID=${DOCKER_OS_GROUPID:-1000}?
        - DOCKER_OS_USERID=${DOCKER_OS_USERID:-1000}
        - DOCKER_OS_USERNAME=${DOCKER_OS_USERNAME:-johndoe}
    user: "${DOCKER_OS_USERID:-1000}:${DOCKER_OS_GROUPID:-1000}"?
    tty: true
    // highlight-next-line
    group_add:?
      // highlight-next-line
      - ${DOCKER_GROUPID:-1001}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock?

Entrez une fois encore dans le container : docker compose up --detach --build && docker compose exec dood /bin/sh

Et réessayez docker ps ; ça marche. Vous avez à nouveau accès à toutes les commandes Docker, comme docker image list.

Sous le capot (passez ceci si vous voulez juste l'utiliser)​

C'est quoi ce groupe 1001 ?​

Comme dit plus haut, pour pouvoir utiliser DooD avec un utilisateur non privilégié, vous devez être membre du groupe docker de l'host (pas du groupe docker que vous trouvez dans le container).

Une façon de récupérer cet ID est de lancer getent group docker | cut -d: -f3. Vous verrez très probablement 1001 puisque c'est l'ID standard de ce groupe.

Donc, pour rendre le script robuste, il suffit d'initialiser la variable DOCKER_GROUPID avant de construire l'image :

$ DOCKER_GROUPID="$(getent group docker | cut -d: -f3)" docker compose up --detach --build && docker compose exec dood /bin/sh▋

Les limites de sécurité de DooD​

Monter /var/run/docker.sock est pratique, mais soyez honnête avec vous-même sur ce que cela accorde : tout processus capable d'atteindre ce socket peut demander au daemon de l'host de démarrer un nouveau container avec presque n'importe quel montage ou privilège, y compris un container qui monte le système de fichiers racine de l'host. En pratique, un accès DooD équivaut à un accès root sur l'host, appartenance à un groupe ou non. Réservez-le à des contextes de confiance (votre propre machine de dev, un runner CI que vous contrôlez) — ne l'exposez jamais à un container qui exécute du code tiers ou non fiable.

Conclusion​

Utiliser Docker-out-of-Docker dans un container qui tourne en root est assez simple — il suffit d'installer docker lors du build de l'image et de monter votre socket Docker.

C'est moins simple avec un utilisateur non privilégié, mais ça devient facile une fois la bonne méthode trouvée : utiliser la propriété group_add et récupérer l'ID du groupe docker local.

L'endroit où cette technique est la plus utile est un runner CI : voir GitLab - Exécuter Docker-out-of-Docker dans votre CI pour la configuration spécifique à GitLab. Pour un usage quotidien du même montage de socket, lazydocker dans un container met un tableau de bord live de tous les containers de l'host à une commande de distance.

Remerciements 🙏​

Merci à Metin Y. (meyay) qui m'a signalé une erreur dans la terminologie que j'utilisais. Dans ma première version, je parlais de la technique décrite ici comme Docker-in-Docker (dind) ; c'était incorrect.

En montant le socket Docker de l'host (/var/run/docker.sock), il s'agit bien de la technique Docker-out-of-Docker.