The Problem

A common goal when learning or testing Ansible is to spin up a small cluster of Docker containers: one container acting as the Ansible control node and one or more containers acting as managed targets. The setup seems straightforward, but many people hit the same wall immediately: Ansible reports that every target is UNREACHABLE.

A typical error looks like this:

fatal: [127.0.0.1]: UNREACHABLE! => {"changed": false, "msg": "[Errno None] Unable to connect to port 9800 on 127.0.0.1", "unreachable": true}

The Ansible inventory (hosts file) in this scenario looks like:

[docker-hosts]
127.0.0.1:9800
127.0.0.1:9801

And a minimal playbook.yml targeting those hosts:

---
- hosts: docker-hosts
  remote_user: root
  become: yes
  become_method: sudo

  tasks:
    - name: pulling docker image
      docker_image:
        name: centos

Run with:

ansible-playbook playbook.yml -f 10

Both 127.0.0.1 and 0.0.0.0 fail as target addresses. Here is why, and how to fix it.

Why 127.0.0.1 Does Not Work Between Containers

Inside any Docker container, 127.0.0.1 (loopback) refers to that container itself, not to the Docker host and not to any sibling container. When the Ansible control container tries to SSH to 127.0.0.1:9800, it is attempting to connect to a port on its own loopback interface — which has nothing listening on it.

Even if you published the target containers’ SSH ports to the Docker host (e.g., -p 9800:22), the host’s loopback is a separate network namespace from the container’s loopback. On Linux you might be able to reach the host via the default bridge gateway IP, but on Docker for Mac there is an additional networking layer (a Linux VM) that makes 127.0.0.1 from inside a container even less reliable for this purpose.

Solution 1: Use a User-Defined Docker Bridge Network

The cleanest approach is to put all containers on the same user-defined bridge network. Docker then provides automatic DNS resolution by container name, so you can address targets by name rather than by IP address.

Step 1 — Create a dedicated network

docker network create ansible-test

Step 2 — Start the target containers on that network

docker run -d --name target1 --network ansible-test --rm centos:latest /usr/sbin/sshd -D
docker run -d --name target2 --network ansible-test --rm centos:latest /usr/sbin/sshd -D

Note: A base CentOS image does not run SSH by default. You will need a custom image that installs and configures openssh-server and sets up SSH keys. See Solution 3 below for an alternative that avoids SSH entirely.

Step 3 — Start the Ansible control container on the same network

docker run -it --name ansible-control --network ansible-test --rm your-ansible-image bash

Step 4 — Update the Ansible inventory to use container names

[docker-hosts]
target1
target2

Docker’s embedded DNS resolves target1 and target2 to the correct container IP addresses automatically. No port mapping to the host is required.

Solution 2: Use Docker Compose to Manage the Network Automatically

Docker Compose creates a dedicated bridge network for each project by default, so all services within one Compose file can reach each other by service name.

version: "3"
services:
  ansible-control:
    image: your-ansible-image
    depends_on:
      - target1
      - target2
    volumes:
      - ./playbooks:/playbooks

  target1:
    image: your-ssh-enabled-centos-image

  target2:
    image: your-ssh-enabled-centos-image

Your Ansible inventory then simply references target1 and target2 by service name.

Solution 3: Use the Docker Connection Plugin Instead of SSH

If the goal is purely to test Ansible playbooks against containers (rather than to test SSH connectivity itself), you can skip SSH altogether. Ansible ships with a docker connection plugin that uses docker exec internally.

Set the connection type in your inventory:

[docker-hosts]
target1 ansible_connection=docker
target2 ansible_connection=docker

With this approach:

• No SSH daemon is needed in the target containers.
• No port publishing or network configuration is required.
• The Ansible control node must be able to run docker exec — either by running on the Docker host itself, or by mounting the Docker socket into the control container (-v /var/run/docker.sock:/var/run/docker.sock).

Why Port-Mapping to the Host Is Not Enough on Its Own

Some guides suggest publishing SSH ports to the host (e.g., -p 9800:22 -p 9801:22) and then pointing Ansible at the host’s IP. This can work when Ansible runs directly on the host, because the host’s loopback or LAN IP is reachable. However, when Ansible itself runs inside a container, the situation changes:

• On Linux, the default Docker bridge gateway (typically 172.17.0.1) is the host’s bridge IP and is reachable from containers. You could use that IP in the inventory.
• On Docker for Mac, the Docker engine runs inside a Linux VM. The host’s localhost is not directly reachable from inside a container using 127.0.0.1. Docker for Mac provides the special hostname host.docker.internal to reach the host machine, but this adds unnecessary complexity.

Using a user-defined network (Solution 1) or the Docker connection plugin (Solution 3) avoids all of this complexity.

Summary

For most local Ansible testing workflows, a user-defined Docker network with container-name-based inventory, or the docker connection plugin, is the recommended approach. Avoid addressing sibling containers via 127.0.0.1 — it refers to the container’s own loopback, not to any other container or to the host.

Note: This tutorial was originally written for an early version of Docker on Ubuntu 12.10 and uses the legacy lxc-docker package and docker commit workflow. The core concepts still apply, but modern Docker installations should use the official Docker Engine packages from docs.docker.com and prefer Dockerfiles over interactive commits. See the review notes at the bottom for details.

Prerequisites

Docker runs on Linux, macOS, Windows, Windows Server, and major cloud platforms including AWS and Azure. The examples below use Ubuntu Linux. The demonstration application is Bitbucket Server (Atlassian’s self-hosted Git repository manager, previously called Stash), but you can substitute any Java application.

Before you start, install a few common utilities on your host machine:

sudo apt-get install vim curl git

Step 1: Install Docker

The following commands show the historical installation path used in the original tutorial (Ubuntu 12.10, lxc-docker package). For current Ubuntu versions, follow the official Docker installation guide instead.

Install kernel extras required by Docker:

sudo apt-get install linux-image-extra-$(uname -r)

Install software-properties-common to gain access to add-apt-repository:

sudo apt-get install software-properties-common

Add the Docker PPA and update package lists:

sudo add-apt-repository ppa:dotcloud/lxc-docker
sudo apt-get update

Install Docker:

sudo apt-get install lxc-docker

Pull a base Ubuntu image to use as your starting point:

docker pull base

Docker will download the image layers and confirm when the pull is complete. If the Docker daemon is not already running, start it in the background:

sudo docker -d &

You can list all images available locally at any time:

docker images

After pulling the base image you should see output similar to:

REPOSITORY   TAG              ID             CREATED
base         ubuntu-quantal   b750fe79269d   10 weeks ago
base         latest           b750fe79269d   10 weeks ago
base         ubuntu-12.10     b750fe79269d   10 weeks ago

Step 2: Install Java Inside a Docker Container

Start an interactive shell inside the base container:

docker run -i -t base /bin/bash

Docker creates a new container, assigns it a unique ID and an internal IP address, and drops you into a root shell:

root@298af82e71ef:/#

Inside the container, install the prerequisite package and add the Java PPA:

apt-get install software-properties-common
add-apt-repository ppa:webupd8team/java
apt-get update

Install Java (you may be prompted to accept the Oracle license agreement):

apt-get install git curl oracle-java7-installer

Exit the container with exit or Ctrl+D, then list all containers (including stopped ones) to find its ID:

docker ps -a

ID             IMAGE          COMMAND      CREATED          STATUS
8e07a84ea97a   base:latest    /bin/bash    12 minutes ago   Exit 0
...

Commit the most recent container (the one where you installed Java) as a new named image:

docker commit 8e07a84ea97a durdn/java7

Verify it appears in your local image list:

docker images

REPOSITORY     TAG      ID             CREATED
durdn/java7    latest   ab6396541f9a   2 hours ago
base           latest   b750fe79269d   10 weeks ago

You now have a reusable Docker image with Java installed. Any future container launched from durdn/java7 starts with Java already present.

Step 3: Install the Java Application in Your Container

Spin up an interactive shell from your new durdn/java7 image. Map container port 7990 to the host and declare a persistent volume at /opt/stash-home for application data:

docker run -i -t -p :7990 -v /opt/stash-home durdn/java7 /bin/bash

Inside the container, download Bitbucket Server (formerly called Stash — hence the file and directory names below):

curl -Lks https://www.atlassian.com/software/stash/downloads/binary/atlassian-bitbucket-4.13.0.tar.gz \
     -o /root/stash.tar.gz

Unpack the archive and set up the application home directory:

mkdir /opt/stash
tar zxf /root/stash.tar.gz --strip=1 -C /opt/stash
mkdir /opt/stash-home
export STASH_HOME=/opt/stash-home

Add the container’s hostname to /etc/hosts to avoid startup errors (replace 298af82e71ef with your actual container ID as shown in the shell prompt):

echo "127.0.0.1 298af82e71ef" >> /etc/hosts

Start the application in the foreground:

/opt/stash/bin/start-stash.sh -fg

Open http://localhost:7990/stash in your browser to confirm the application is running.

Exit the container, then commit the state to a new image:

docker commit aec2feb8cdea durdn/stash

You now have a durdn/stash image with Bitbucket Server installed and ready to launch.

Ephemeral Containers and Persistent Storage

Docker containers are ephemeral: when a container is removed, its writable layer is discarded and the container resets to its image state. Without persistence, application data is lost every time you stop and remove a container.

The solution is Docker volumes. Volumes exist independently of any individual container and can be shared between containers. In the older Docker API shown here, the --volumes-from flag reuses the volume from a previously run container.

Start Bitbucket Server interactively, reusing the data volume from the earlier container:

docker run -i -t -p :7990 --volumes-from aec2feb8cdea durdn/stash \
  /bin/bash -c 'STASH_HOME=/opt/stash-home /opt/stash/bin/start-stash.sh -fg'

To run the container in the background (detached mode), replace -i -t with -d:

docker run -d -p :7990 --volumes-from aec2feb8cdea durdn/stash \
  /bin/bash -c 'STASH_HOME=/opt/stash-home /opt/stash/bin/start-stash.sh -fg'

Confirm the container is running:

docker ps

Your application is now running in the background with data persisted across container restarts.

Modern Alternatives: Dockerfiles and Official Images

The interactive docker commit workflow demonstrated above is useful for understanding how Docker layers work, but production workflows typically use Dockerfiles. A Dockerfile codifies every step as a reproducible build instruction, making images auditable and easy to rebuild.

For Java applications, Docker Hub provides official images such as eclipse-temurin and amazoncorretto that eliminate the need to manually install a JDK. A minimal Dockerfile for a Java application might look like this:

# Use an official JDK base image
FROM eclipse-temurin:21-jre

# Copy the application JAR into the image
COPY target/myapp.jar /app/myapp.jar

# Expose the application port
EXPOSE 8080

# Run the application
CMD ["java", "-jar", "/app/myapp.jar"]

Build the image with:

docker build -t myapp:latest .

And run it with a named volume for data persistence:

docker run -d -p 8080:8080 -v myapp-data:/data myapp:latest

Key Takeaways

• Docker containers provide a portable, repeatable runtime environment for Java applications without requiring configuration changes on the host system.
• The docker commit approach turns a running container into a reusable image — useful for learning, but Dockerfiles are the standard for production builds.
• Containers are ephemeral by default. Use Docker volumes (-v or --volumes-from) to persist data between container runs.
• For modern Java workloads, start from an official JDK image on Docker Hub rather than installing Java manually inside a generic base image.
• Use docker ps to list running containers and docker ps -a to include stopped ones.

The Problem: Two Separate Network Contexts

A proxy misconfiguration with Docker almost always comes down to one misunderstood fact: there are two separate network contexts that each need independent proxy settings.

• The Docker daemon — responsible for pulling base images from registries such as Docker Hub.
• The container build/run environment — the isolated environment in which your RUN instructions execute. Tools like apt-get, yum, curl, and pip run here and have no knowledge of the host’s proxy settings.

Configuring one without the other will leave you with partial failures. The sections below address each context in turn.

A Simple Example Dockerfile

Throughout this article we will use a minimal Ubuntu-based image that installs curl via apt-get. This is intentionally simple, but it exercises both proxy contexts.

FROM ubuntu

RUN apt-get update && apt-get install -y curl

Attempting to build this image on a network with no direct internet access produces an error immediately at the FROM step:

$ sudo docker build -t curl .
Sending build context to Docker daemon 12.29 kB
Step 0 : FROM ubuntu
Pulling repository ubuntu
INFO[0002] Get https://index.docker.io/v1/repositories/library/ubuntu/images: dial tcp 52.22.146.88:443: connection refused

The daemon cannot reach Docker Hub because outbound TCP connections are blocked. Fix this first.

Step 1 — Configuring the Docker Daemon to Use a Proxy (Ubuntu host)

On Ubuntu hosts that use the older SysV init system, Docker’s environment is sourced from /etc/default/docker. That file includes a commented-out proxy line:

# If you need Docker to use an HTTP proxy, it can also be specified here.
#export http_proxy="http://127.0.0.1:3128/"

Uncomment the line and replace the placeholder with your actual proxy address:

# If you need Docker to use an HTTP proxy, it can also be specified here.
export http_proxy="http://192.168.33.10:3128/"

If your proxy requires authentication, embed the credentials in the URL:

export http_proxy="http://username:password@192.168.33.10:3128/"

systemd-based hosts

Most modern Ubuntu and Debian installations (16.04 and later) manage Docker with systemd, which does not read /etc/default/docker for environment variables. For systemd, create a drop-in override file instead:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf <<EOF
[Service]
Environment="HTTP_PROXY=http://192.168.33.10:3128/"
Environment="HTTPS_PROXY=http://192.168.33.10:3128/"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

For the SysV approach, restart Docker with the service command:

# service docker restart
docker stop/waiting
docker start/running, process 32703

After restarting, docker pull and the FROM step of a build will route through your proxy. However, RUN instructions that use apt-get or other network tools will still fail because the container environment has no proxy configured.

Step 2 — Configuring the Proxy Inside the Container

After configuring the daemon proxy, re-running the build pulls the Ubuntu base image successfully — but apt-get update immediately fails:

Step 1 : RUN apt-get update && apt-get install -y curl
 ---> Running in 39b964be90bc
Err:1 http://archive.ubuntu.com/ubuntu xenial InRelease
  Cannot initiate the connection to archive.ubuntu.com:80. - connect (101: Network is unreachable)
E: Unable to locate package curl

This happens because the container’s network environment is isolated from the host. The http_proxy variable set on the host is not inherited inside the container’s build shell.

Option A — Pass proxy settings as build arguments

Use --build-arg to inject the proxy at build time without hardcoding it in the Dockerfile:

$ sudo docker build -t curl \
  --build-arg http_proxy=http://192.168.33.10:3128 \
  --build-arg https_proxy=http://192.168.33.10:3128 \
  .

This approach is preferred when you want to keep the Dockerfile portable — colleagues on networks without a proxy can build the same file without modification.

Option B — Set proxy variables in the Dockerfile with ENV

Alternatively, declare the proxy variables directly in the Dockerfile using ENV instructions:

FROM ubuntu

ENV http_proxy "http://192.168.33.10:3128"
ENV https_proxy "http://192.168.33.10:3128"
RUN apt-get update && apt-get install -y curl

Both apt-get and curl respect the standard http_proxy / https_proxy environment variables, so this is sufficient for most Linux package managers and command-line HTTP tools.

Step 3 — Verifying the Build and Runtime Behaviour

With proxy variables set, the build completes successfully:

$ sudo docker build -t curl .
...
Step 1 : ENV http_proxy "http://192.168.33.10:3128"
Step 2 : ENV https_proxy "http://192.168.33.10:3128"
Step 3 : RUN apt-get update && apt-get install -y curl
Get:1 http://archive.ubuntu.com/ubuntu xenial InRelease [247 kB]
Get:2 http://archive.ubuntu.com/ubuntu xenial-updates InRelease [102 kB]
...

Running the container and making an outbound request with curl shows that traffic is also routed through the proxy at runtime:

$ sudo docker run curl curl -v http://example.com
*   Trying 192.168.33.10...
> GET http://example.com/ HTTP/1.1
> Proxy-Connection: Keep-Alive
< HTTP/1.1 200 OK

Notice the Proxy-Connection header — the request was forwarded via the proxy.

Unsetting Proxy Variables After the Build Step

Because ENV instructions persist into the running container, any process that respects http_proxy will automatically use the proxy at runtime — which may not be what you want if the proxy is only reachable from the build network. To scope proxy settings to the build phase only, unset them after your package installation step:

FROM ubuntu

ENV http_proxy "http://192.168.33.10:3128"
ENV https_proxy "http://192.168.33.10:3128"
RUN apt-get update && apt-get install -y curl
ENV http_proxy ""
ENV https_proxy ""

When the container is launched with docker run, the proxy variables will be empty and outbound connections from application code will go directly to the network (or fail gracefully if the runtime network also requires a proxy).

Alternatively, you can override environment variables at runtime without modifying the Dockerfile:

$ sudo docker run -e http_proxy="" -e https_proxy="" curl curl http://example.com

Docker Desktop (Mac and Windows)

Docker Desktop on macOS and Windows exposes proxy settings through the application’s graphical preferences panel. Navigate to Settings → Resources → Proxies and enable Manual proxy configuration to specify HTTP and HTTPS proxy addresses.

This configures the Docker Desktop daemon’s outbound proxy for image pulls. It does not automatically inject proxy variables into container build or run environments — you still need to use ENV instructions or --build-arg for that.

Quick Reference: Which Setting Does What

Summary

Getting Docker to work behind a corporate proxy requires addressing two independent layers:

1. The Docker daemon — configure HTTP_PROXY / HTTPS_PROXY via the systemd drop-in file (modern systems) or /etc/default/docker (older SysV systems), then restart the service.
2. The container environment — pass proxy settings via --build-arg or ENV instructions in the Dockerfile so that package managers and other tools inside the container can reach external repositories.

Remember that ENV-declared proxy variables persist into the running container. Unset them after your installation steps, or override them with docker run -e, if you do not want runtime traffic to traverse the proxy.

Overview

By default, Mesosphere DC/OS runs workloads inside Docker containers to minimize host OS dependencies and to provide resilience against node failures. When you use Jenkins on DC/OS, the underlying Mesos scheduler dynamically creates Jenkins build agents as Mesos tasks, each running inside a Docker container. Your configured build steps then execute inside that same container.

Because builds commonly invoke Docker commands such as docker build or docker push, Mesosphere provides the mesosphere/jenkins-dind image (Docker-in-Docker) and configures Jenkins for DC/OS to use it by default. The image ships with several widely-used tools; the authoritative list is in the upstream Dockerfile.

If your builds require environment-specific packages or configurations that are not present in the default image, you can create a custom Docker image, push it to Docker Hub or a private registry, and point Jenkins at it. That registry must be reachable from every DC/OS agent node.

Minimum Requirements for a Custom Agent Image

At a minimum, every custom Jenkins agent image must include:

• OpenJDK 8 — Required by Jenkins to launch the agent process and register it with the Jenkins master.
• CA certificates — Required to verify SSL/TLS certificates when the agent communicates with external services.

The following packages are not strictly required but are commonly needed by build scripts:

• Bash — Many Jenkins build scripts rely on Bash as their shell interpreter.
• Git — Required to check out source code from Git repositories.
• OpenSSH client — Required when cloning repositories over SSH.

Creating a Custom Image Based on mesosphere/jenkins-dind

The recommended approach is to extend the official mesosphere/jenkins-dind base image rather than building a new image from scratch. This ensures you inherit the correct Java runtime, CA certificates, Docker daemon setup, and other baseline configuration.

The following example Dockerfile adds sbt (Scala Build Tool) to the base image. The RUN instruction downloads and extracts the sbt tarball into /usr/local and records the installed version in a build manifest file. (This pattern is adapted from the 1science/docker-sbt Dockerfile.)

FROM mesosphere/jenkins-dind:0.2.2

ENV SBT_VERSION 0.13.8
ENV SBT_HOME /usr/local/sbt
ENV PATH ${PATH}:${SBT_HOME}/bin

RUN curl -sL "http://dl.bintray.com/sbt/native-packages/sbt/$SBT_VERSION/sbt-$SBT_VERSION.tgz" \
    | gunzip | tar -x -C /usr/local \
    && echo "- with sbt $SBT_VERSION" >> /root/.built

After writing your Dockerfile, build and push the image:

# Build the image
docker build -t myorg/jenkins-agent-scala:latest .

# Push to Docker Hub (or substitute your private registry hostname)
docker push myorg/jenkins-agent-scala:latest

Ensure the image is accessible from all DC/OS agent nodes. If you are using a private registry, configure DC/OS agent credentials accordingly.

Managing SSH Host Keys

The default jenkins-dind image ships with GitHub’s SSH public keys pre-populated in /etc/ssh/ssh_known_hosts. If your Git server is not GitHub, SSH-based cloning will fail with a host-key verification error unless you add your server’s public key to that file.

Add the following lines to your Dockerfile, replacing my.git.server with your actual Git server hostname:

ENV SSH_KNOWN_HOSTS github.com my.git.server
RUN ssh-keyscan $SSH_KNOWN_HOSTS | tee /etc/ssh/ssh_known_hosts

ssh-keyscan contacts each hostname and writes its public key to stdout. Piping the output to tee appends the keys to the known-hosts file inside the image, so the SSH client will not prompt for confirmation at clone time.

Configuring Jenkins to Use the Custom Image

Once your custom image is available in a registry, you need to register it as a slave configuration in Jenkins so it can be selected by individual jobs.

1. In the Jenkins web UI, go to Manage Jenkins → Configure System.
2. Scroll to the Cloud section and click Advanced. A grey Add Slave Info button will appear.

   

3. Fill in the slave info fields. Key settings include:
   • Label string — A unique label you will use in job configurations to target this agent (for example, scala-agent).
   • Usage — Leave as the default (Utilize this node as much as possible) unless you have a specific reason to restrict it.
   • Jenkins slave CPUs — CPU shares allocated to the agent container itself.
   • Jenkins slave memory in MB — Memory allocated to the agent container itself.
   • Maximum number of executors per slave — How many Jenkins executors will run inside the single container.
   • Jenkins executor CPUs — Estimated CPU shares per executor.
   • Jenkins executor memory — Estimated memory per executor.

   The actual resources requested from Mesos are calculated as follows:

   actualCpus = slaveCpus + (maxExecutors * executorCpus)
   actualMem  = slaveMem  + (maxExecutors * executorMem)

   

4. Click Advanced again to expose the containerizer options. Select Use Docker Containerizer and enter your custom image name in the Docker Image field (for example, myorg/jenkins-agent-scala:latest).

   

   Note: If your custom image is a Docker-in-Docker image (that is, it needs to run Docker commands inside the container), you must also enable Docker Privileged Mode and specify a custom Docker command shell in this panel.

5. Click Save.

Targeting the Custom Agent from a Jenkins Job

After the slave configuration is saved, you can restrict any job to run on the new agent by referencing its label.

1. Open the job and click Configure.
2. Check Restrict where this project can be run.
3. Enter the Label String you defined in the slave configuration (for example, scala-agent).

   

4. Click Save.

When the job is triggered, the Mesos scheduler will spin up a new agent container using your custom image and route the build to it.

Summary

Customizing Docker containers for Jenkins agents on DC/OS follows a straightforward workflow:

• Extend mesosphere/jenkins-dind with your dependencies.
• Add any required SSH host keys at image build time.
• Push the image to a registry accessible by all DC/OS agent nodes.
• Register the image as a new slave configuration in Jenkins, assigning it a label.
• Restrict individual jobs to that label so they run on the correct agent image.

This pattern keeps build environments reproducible and version-controlled without modifying the DC/OS host nodes directly.

Why Docker Container Portability Matters

One of the most compelling reasons teams adopt Docker is the ability to build an application once and run it consistently across laptops, on-premises servers, and public cloud environments. A container that passes QA on a developer’s workstation behaves identically in staging and production because the entire runtime environment — libraries, configuration, and application code — is bundled into the container image.

This stands in sharp contrast to traditional deployment models, where differences in operating system versions, installed packages, or environment variables frequently caused the dreaded “works on my machine” problem.

The Foundation: Docker Images and Layers

A Docker image is not a single monolithic file. Instead, it is composed of a stack of read-only layers, each representing a discrete set of filesystem changes. When you write a Dockerfile, each instruction (FROM, RUN, COPY, ADD, etc.) typically produces a new layer on top of the previous one.

# Example Dockerfile illustrating layer creation
FROM ubuntu:22.04          # Layer 1 – base OS
RUN apt-get update && \
    apt-get install -y python3  # Layer 2 – installed packages
COPY app/ /app             # Layer 3 – application code
CMD ["python3", "/app/main.py"]

Each layer is content-addressed using a cryptographic hash. Docker (and the OCI image specification it influenced) can therefore:

• Cache layers locally — if a layer already exists on the host, it is not downloaded again.
• Share layers between images — two images that share the same base layer store that layer only once on disk.
• Verify integrity — any tampering with a layer changes its hash, making it immediately detectable.

Copy-on-Write: The Key to Efficient Portability

When Docker starts a container from an image, it does not copy all the image data into a new location. Instead, it adds a thin, writable container layer on top of the read-only image layers. This is the copy-on-write (CoW) strategy.

Here is how CoW works in practice:

1. Read operations are served directly from whichever image layer contains the file — no copying occurs.
2. Write operations trigger a copy of the targeted file from the image layer up into the writable container layer. Subsequent writes to the same file stay in the container layer.
3. Deletes are recorded as a “whiteout” marker in the container layer; the underlying image layer is left untouched.

The practical result is that spinning up dozens of containers from the same image consumes very little additional disk space — each container only stores its own delta, not a full copy of the image.

Storage Drivers That Implement CoW

Docker delegates the actual CoW filesystem work to a pluggable storage driver. Common options include:

overlay2 is the recommended and most widely used driver. It uses the Linux kernel’s OverlayFS to merge multiple directory trees into a single unified view, providing excellent performance and broad compatibility.

How Portability Is Achieved End-to-End

Combining layered images with CoW storage enables the full portability workflow:

1. Build — docker build assembles layers from a Dockerfile and tags the resulting image.
2. Push — docker push uploads only the layers that the target registry does not already have.
3. Pull — on any Docker host, docker pull downloads only the missing layers.
4. Run — docker run instantiates a container in seconds by adding a writable CoW layer; no full image copy is needed.

Because the image layers are immutable and content-addressed, the container running in a CI pipeline is byte-for-byte identical to the one that will run in production — regardless of the underlying host OS distribution, cloud provider, or hardware architecture (assuming the same CPU architecture).

Additional Factors That Reinforce Portability

Layered storage is the core mechanism, but several other Docker features reinforce portability:

• Self-contained environment — the image bundles all dependencies, eliminating reliance on host-installed libraries.
• Environment variables and secrets injection — runtime configuration is passed at docker run time, keeping images environment-agnostic.
• Docker Compose and orchestration manifests — multi-container applications are described declaratively, making entire stacks reproducible across environments.
• OCI standards — Docker images conform to the Open Container Initiative (OCI) image specification, meaning they can be run by any OCI-compliant runtime (containerd, Podman, etc.), not just the Docker Engine.

Limitations to Keep in Mind

Docker container portability is powerful but not absolute. Key constraints include:

• CPU architecture — an image built for amd64 will not run natively on arm64 without multi-platform build support (docker buildx).
• Kernel dependencies — containers share the host kernel. Workloads that require a specific kernel version or kernel module may not be fully portable.
• Persistent data — data written inside the CoW container layer is ephemeral. Production applications must use Docker volumes or bind mounts for data that must survive container restarts.
• Windows vs. Linux containers — Windows and Linux containers require matching host operating systems; they are not interchangeable.

Summary

Docker’s portability stems from a well-designed combination of immutable, content-addressed image layers and a copy-on-write strategy implemented by the host’s storage driver. Together, these mechanisms allow teams to build an application image once and deploy it reliably across development, staging, and production environments — on-premises or in any public cloud — with minimal overhead and maximum consistency.