docker-in-docker.md

Docker-in-Docker Install Script

Interested in running docker commands from inside a container? Chances are the Docker-from-Docker technique may suit your needs better.

Create child containers inside a container, independent from the host's docker instance. Installs Docker extension in the container along with needed CLIs.

Script status: Stable

OS support: Debian 9+, Ubuntu 20.04+, and downstream distros.

Note: Your host chip architecture needs to match the your container image architecture for this script to function. Cross-architecture emulation will not work.

Maintainer: The VS Code and GitHub Codespaces teams

Syntax

./docker-in-docker-debian.sh [enable non-root docker access flag] [non-root user] [use moby]

Argument	Default	Description
Non-root access flag	true	Flag (true/false) that specifies whether a non-root user should be granted access to Docker.
Non-root user	automatic	Specifies a user in the container other than root that will be using the desktop. A value of automatic will cause the script to check for a user called vscode, then node, codespace, and finally a user with a UID of 1000 before falling back to root.
Use Moby	true	Specifies that a build of the open source Moby CLI should be used instead of the Docker CLI distribution of it.

Usage

See the docker-in-docker definition for a complete working example. However, here are the general steps to use the script:

1. Add docker-in-docker-debian.sh to .devcontainer/library-scripts

2. Add the following to your .devcontainer/Dockerfile:

   # If "context" is set to ".." in devcontainer.json, use .devcontainer/library-scripts/*.sh
   COPY library-scripts/*.sh /tmp/library-scripts/
   
   ENV DOCKER_BUILDKIT=1
   RUN apt-get update && /bin/bash /tmp/library-scripts/docker-in-docker-debian.sh
   ENTRYPOINT ["/usr/local/share/docker-init.sh"]
   VOLUME [ "/var/lib/docker" ]
   CMD ["sleep", "infinity"]

   Note that the ENTRYPOINT script can be chained with another script by adding it to the array after docker-init.sh.

3. And the following to .devcontainer/devcontainer.json if you are referencing an image or Dockerfile:

   "runArgs": ["--init", "--privileged"],
   "overrideCommand": false

   Or if you are referencing a Docker Compose file, add this to your docker-compose.yml file instead:

   your-service-name-here:
     init: true 
     privileged: true
     # ...

   The dind-var-lib-docker volume mount is optional but will ensure that containers / volumes you create within the dev container survive a rebuild. You should update dind-var-lib-docker with a unique name for your container to avoid corruption when multiple containers write to it at the same time.

   While technically optional, --init enables an init process to properly handle signals and ensure Zombie Processes are cleaned up.

4. If you want any containers or volumes you create inside the container to survive it being deleted, you can use a "named volume". And the following to .devcontainer/devcontainer.json if you are referencing an image or Dockerfile replacing dind-var-lib-docker with a unique name for your container:

   "mounts": ["source=dind-var-lib-docker,target=/var/lib/docker,type=volume"]

   Or if you are referencing a Docker Compose file, add this to your docker-compose.yml file instead:

   your-service-name-here:
     # ...
     volumes:
       - dind-var-lib-docker:/var/lib/docker
     # ...

5. If you are running the container as something other than root (either via USER in your Dockerfile or containerUser), you'll need to ensure that the user has sudo access. (If you run the container as root and just reference the user in remoteUser you will not have this problem, so this is recommended instead.) The debian-common.sh script can do this for you, or you set one up yourself.

Resources

This docker-in-docker definition is roughly based on the official docker-in-docker wrapper script. The original blog post on this concept can be found here.