View source for HowItWorks:Docker

{{HowItWorks}}

Written in Go and built on top of Linux kernel,'''Docker''' packages an application — code, runtime, libraries, configuration — into a '''container''': a loosely isolated environment that runs the same on any device: on a developer's laptop like on a data centre server<ref>{{#cite:Q1407}}</ref> <ref>{{#cite:Q1407}}</ref>.

== Container ? ==

A '''container''' is an isolated, self-sufficient process without external dependencies. It contains all the files it needs to run, making it extremely portable.<ref>{{#cite:Q1408}}</ref>

Programmatically independent but sharing the host's kernel, a Docker container offers the full isolation provided by '''Virtual Machines (VM)''' at a fraction of the resource overhead.<ref>{{#cite:Q1408}}</ref>

=== A short history ===

Docker was first pioneered by [[Person:Solomon Hykes|Solomon Hykes]], founder of dotCloud, as an internal project to solve virtualisation bottlenecks for his company's PaaS service. 

In March 2013, it was decided to open-source the project, so, as Hykes himself described, that "pioneers can start to use containers and collaborate in a monolithic open source codebase: Docker".<ref>{{#cite:Q1415}}</ref>

The opensourced Docker became an instant hit. By October 2013, seven months after the project's first open-source pre-release, Docker was downloaded more than 140,000 times, and forked more than 800 times on Github.<ref>{{#cite:Q1426}}</ref> It was so popular that dotCloud decided to rename itself Docker, Inc.<ref>{{#cite:Q1421}}</ref>

Docker 1.0, the first production-ready release, shipped on June 9, 2014.<ref>{{#cite:Q1417}}</ref>

In 2015, Docker's container format and runtime became the cornerstone of the newly written open standards for containers under the Open Container Initiative (OCI) led by the [[Collective:The Linux Foundation|Linux Foundation]].<ref>{{#cite:Q1418}}</ref>.

In 2016, the core container runtime of Docker was spun out into a standalone project called [[FOSS:Containerd|containerd]] and donated to the Cloud Native Computing Foundation (CNCF).<ref>{{#cite:Q1416}}</ref><ref>{{#cite:Q1405}}</ref>

In 2017, [[FOSS:Moby Project|the Moby Project]] was launched to host all open-source collaboration around Docker.<ref>{{#cite:Q1415}}</ref> It aims to provide "an open framework to assemble specialized container systems without reinventing the wheel".<ref>{{#cite:Q1427}}</ref>

As of August 2026, the Moby project's Github repo has more than 2330 contributors, and 19.2k forks.<ref>{{#cite:Q1431}}</ref>

== Components and interactions ==

Docker uses a client-server architecture: the '''Docker client''' talks to the '''Docker daemon''' (dockerd), which does "the heavy lifting of building, running, and distributing" containers, over a REST API on a UNIX socket or network interface.<ref>{{#cite:Q1407}}</ref> The daemon manages Docker objects — images, containers, networks, volumes, plugins — and can even communicate with other daemons (for Docker services).<ref>{{#cite:Q1407}}</ref> Another client, besides the CLI, is [[FOSS:Docker Compose|Docker Compose]], for multi-container applications.<ref>{{#cite:Q1407}}</ref>

Modern Docker Engine is not one monolith but a stack of cooperating components:

<uml>
@startuml
!theme bluegray
title Docker Components and Interactions

' ============= CLIENT SIDE =============
node "Client" {
  [""docker"" CLI] as CLI
  [Docker Compose] as COMPOSE
}

' ============= HOST =============
node "Host" {
  component "dockerd\nDocker daemon\n(Engine API: images, containers,\nnetworks, volumes)" as DOCKERD
  component "containerd\n(container lifecycle, image store,\nsnapshots, exec)" as CONTAINERD
  component "containerd-shim\n(keeps stdio open,\nallows daemon restart)" as SHIM
  component "runc\n(OCI runtime: namespaces,\ncgroups, pivot_root)" as RUNC
  database "Linux kernel\n(namespaces, cgroups v2,\nOverlayFS, seccomp)" as KERNEL
}

' ============= DISTRIBUTION & BUILD =============
node "Distribution / Build" {
  database "Registry\n(Docker Hub by default)" as REGISTRY
  component "BuildKit\n(build executor)" as BUILDKIT
}

' ============= FLOWS =============
CLI --> DOCKERD : REST API\n(UNIX socket / TCP)
COMPOSE --> DOCKERD : REST API
DOCKERD --> CONTAINERD : gRPC (containerd client)
CONTAINERD --> SHIM : task lifecycle
SHIM --> RUNC : OCI runtime spec
RUNC --> KERNEL : clone(), unshare(),\npivot_root()
DOCKERD --> REGISTRY : pull / push\n(registry HTTP API v2)
DOCKERD --> BUILDKIT : build requests
BUILDKIT --> REGISTRY : push / cache export

note right of CLI
  The docker CLI is a thin client:
  it formats requests and renders
  responses; all state lives in
  the daemon.
end note
note right of CONTAINERD
  Since Docker Engine 1.11 (2016)
  dockerd delegates container
  execution to containerd.
end note
note right of RUNC
  runc is the reference
  implementation of the
  OCI runtime spec.
end note
note right of KERNEL
  A container is a set of processes
  isolated by namespaces and
  limited by cgroups — no guest OS.
end note

@enduml
</uml>

The responsibilities are split roughly as follows:

* '''dockerd''' — the API server and object manager. It receives every request, holds the state of images/containers/networks/volumes, and orchestrates the rest of the stack.<ref>{{#cite:Q1407}}</ref>
* '''containerd''' — "an industry-standard container runtime", a daemon that "manages the complete container lifecycle of its host system, from image transfer and storage to container execution and supervision to low-level storage to network attachments and beyond".<ref>{{#cite:Q1405}}</ref> Since Docker Engine 29, the containerd image store is the default for fresh installs.<ref>{{#cite:Q1411}}</ref>
* '''runc''' — the OCI runtime that actually creates and runs container processes, applying namespaces, cgroups and filesystem isolation; it is the reference implementation of the OCI runtime specification.<ref>{{#cite:Q1418}}</ref>
* '''containerd-shim''' — the small per-container process that keeps the container's stdio open and lets the daemons restart without killing containers.
* '''The Linux kernel''' — the isolation primitives themselves: namespaces (each container gets its own set), cgroups for resource limits, OverlayFS for layered filesystems, seccomp and capabilities for security.<ref>{{#cite:Q1407}}</ref>
* '''A registry''' — stores and distributes images; Docker Hub is the default, and <code>docker pull</code>/<code>docker run</code> fetch from it while <code>docker push</code> uploads to it.<ref>{{#cite:Q1407}}</ref>
* '''BuildKit''' — the builder backend that executes image builds; since its adoption it is "the default builder for Docker Desktop and Docker Engine users".<ref>{{#cite:Q1412}}</ref>

== Docker in action ==

Two flows cover most of what Docker does: '''building''' an image from a Dockerfile, and '''running''' a container from an image.

=== Image build ===

To build your own image you write a '''Dockerfile''', "a text document that contains all the commands a user could call on the command line to assemble an image".<ref>{{#cite:Q1410}}</ref> Each instruction — <code>FROM</code>, <code>RUN</code>, <code>COPY</code>, <code>CMD</code>, <code>ENTRYPOINT</code>, ... — becomes a layer of the image.<ref>{{#cite:Q1407}}</ref> Because layers are immutable and cached, "when you change the Dockerfile and rebuild the image, only those layers which have changed are rebuilt" — the main reason images are so lightweight and builds so fast compared with other virtualization technologies.<ref>{{#cite:Q1407}}</ref>

<uml>
@startuml
!theme bluegray
title Image build flow (docker build)

|#LightGray|User|
start
:write a Dockerfile;
|#LightBlue|docker CLI|
:docker build -t myapp .\n(send build context);
|#LightGreen|BuildKit|
:parse the Dockerfile via a frontend\n(convert it to an LLB build graph);
:resolve the base image (FROM);
if (instruction cached?) then (yes)
  :reuse the cached layer;
else (no)
  :run the instruction in a build container;
  :commit the result as a new immutable layer;
endif
:parallelize independent stages,\nskip unused stages;
:assemble the layers into an image\n(config + manifest, content-addressed);
|#LightGray|User|
:myapp:latest is ready\n(docker image ls);
stop

@enduml
</uml>

Underneath the classic <code>docker build</code> command sits BuildKit. Its core is a Low-Level Build (LLB) format: "a content-addressable dependency graph" that lets it detect and skip unused build stages, run independent stages in parallel, and transfer only the changed files of the build context.<ref>{{#cite:Q1412}}</ref> A "frontend" — itself distributed as an image — turns the human-readable Dockerfile into LLB, so the Dockerfile language can evolve without rebuilding the engine.<ref>{{#cite:Q1412}}</ref>

=== Container run ===

A container is "a runnable instance of an image", "defined by its image as well as any configuration options you provide to it when you create or start it".<ref>{{#cite:Q1407}}</ref> When you run <code>docker run -i -t ubuntu /bin/bash</code>, the documented sequence is:<ref>{{#cite:Q1407}}</ref>

# If the <code>ubuntu</code> image is not present locally, Docker pulls it from the configured registry.
# Docker creates a new container (as with <code>docker container create</code>).
# Docker allocates a read-write filesystem to the container as its final layer — the only layer a running container may write to.
# Docker creates a network interface connecting the container to the default network and assigns it an IP address.
# Docker starts the container and executes <code>/bin/bash</code>, attached to your terminal.
# When you type <code>exit</code>, the container stops but is '''not''' removed — you can start it again or delete it.

<uml>
@startuml
!theme bluegray
title Container run flow (docker run -i -t ubuntu /bin/bash)

|#LightGray|User|
start
:docker run -i -t ubuntu /bin/bash;
|#LightBlue|docker CLI|
:POST /containers/create\n(Engine API, negotiated version);
|#LightGreen|dockerd|
if (ubuntu image present locally?) then (no)
  |#LightYellow|Registry|
  :pull image manifest and layers;
  |#LightGreen|dockerd|
  :store layers content-addressed\nin the image store;
else (yes)
endif

:create the container\n(configuration + image);
:allocate a read-write filesystem\n(final layer, copy-on-write);
|#LightPink|containerd|
:create a task, prepare snapshot;
|#Orange|runc|
:create namespaces, apply cgroups,\noverlay mount, pivot_root;
:exec /bin/bash as PID 1;
|#LightGreen|dockerd|
:create network interface,\nconnect to the default bridge network,\nassign an IP address;
:attach stdin / stdout / stderr;
|#LightGray|User|
:interactive shell inside the container;
:exit;
note right
  The container stops but is not
  removed; runtime changes live in
  its writable layer and vanish
  with the container unless stored
  in persistent storage.
end note
stop

@enduml
</uml>

That last point is important: "when a container is removed, any changes to its state that aren't stored in persistent storage disappear."<ref>{{#cite:Q1407}}</ref> Data that must survive goes into '''volumes''' or bind mounts; ephemeral state simply dies with the container.

== Key design decisions ==

=== Containers share the host kernel ===

The founding decision: a container is '''not''' a mini-VM. Docker uses Linux '''namespaces''' to give each container an isolated view (processes, networking, filesystem, users, and more), and '''cgroups''' to limit CPU, memory and I/O.<ref>{{#cite:Q1407}}</ref> Because every container on a host shares the same kernel, there is no guest OS to boot, so containers start in seconds and many more fit on a machine than VMs would.<ref>{{#cite:Q1408}}</ref>

The trade-off is architectural: isolation is as good as the kernel's — and the admin's — configuration. Docker historically defaulted to cgroups v1; the ecosystem has since moved to '''cgroups v2''', and as of Docker Engine 29 cgroup v1 is deprecated but supported until at least May 2029.<ref>{{#cite:Q1411}}</ref> On macOS and Windows, Docker Desktop bundles the daemon, the client, Docker Compose, Kubernetes and more, so the same Linux-based engine is available everywhere.<ref>{{#cite:Q1407}}</ref>

=== Images are immutable, layered and content-addressed ===

An image is a "read-only template", often "based on other images, with some additional customization" — e.g. the Ubuntu image plus the Apache web server plus your application.<ref>{{#cite:Q1407}}</ref><ref>{{#cite:Q1409}}</ref>.

As most consumer images are a combination of base images with customisation, they can be considered as the sum of multiple '''layers'''. Docker identifies them by a hash of their content, and identical layers are shared between images via '''content-addressable storage''', which means they are only downloaded and stored once, regardless of the number of consumer images.<ref>{{#cite:Q1409}}</ref>

* '''Union filesystems''' — at run time, layers are stacked into a single unified view; the container's root is set to that view with <code>chroot</code>. On top of the read-only image layers, a directory is created for the running container, so the container writes without ever touching the image. For additional robustness, Docker uses copy-on-write. <ref>{{#cite:Q1409}}</ref>

This design ensures that images are always state-consistent and optimised for network distribution and storage.

=== The Dockerfile is a declarative build recipe ===

Rather than mutating a running machine (and hoping the result is reproducible), Docker builds images from a declarative '''Dockerfile''' — "all the commands a user could call on the command line to assemble an image".<ref>{{#cite:Q1410}}</ref> A valid Dockerfile must start with <code>FROM</code>, which "initializes a new build stage and sets the base image".<ref>{{#cite:Q1410}}</ref> The key instructions:

* <code>RUN</code> — "execute any commands to create a new layer on top of the current image".<ref>{{#cite:Q1410}}</ref>
* <code>COPY</code> / <code>ADD</code> — copy files from the build context (or another stage) into the image.
* <code>CMD</code> / <code>ENTRYPOINT</code> — define the command executed when a container starts; <code>ENTRYPOINT</code> configures the container to run "as an executable", <code>CMD</code> provides default arguments.<ref>{{#cite:Q1410}}</ref>
* Multiple <code>FROM</code> lines enable '''multi-stage builds''' — build in one stage, copy only the artifacts into a minimal final stage.<ref>{{#cite:Q1410}}</ref>

Because each instruction is a layer, the instruction sequence is also the cache key: <code>RUN</code> layers are reused on rebuild unless invalidated — a changed <code>COPY</code> or <code>ADD</code> invalidates the cache — so instructions placed early in the file are the ones that get reused across builds.<ref>{{#cite:Q1410}}</ref> BuildKit hardened this model by tracking "the checksums of build graphs" instead of heuristics, making the cache faster, more precise and portable — it can even be exported to a registry.<ref>{{#cite:Q1412}}</ref>

=== A daemon-centric client-server design ===

Docker chose a single privileged '''daemon''' that owns all state, fronted by a deliberately thin CLI.<ref>{{#cite:Q1407}}</ref> Every <code>docker</code> command is a REST call to the Engine API; the daemon performs it and reports back.<ref>{{#cite:Q1407}}</ref> This concentrates complexity in one place (good for security auditing and for the object model) and makes the engine scriptable — CI systems, orchestrators and tools like [[FOSS:Docker Compose|Compose]] and Docker Desktop are just API clients.<ref>{{#cite:Q1407}}</ref>

The cost: a single point of failure and a long-lived process, which is precisely what the containerd extraction (below) addressed — the low-level container lifecycle moved out of the daemon, so the daemon can restart without killing containers.

=== The Engine API is versioned and stable ===

Like MediaWiki's parser stability, Docker's contract with the outside world is its '''versioned Engine API'''. Clients and daemons negotiate the API version, so a newer CLI can drive an older daemon and vice versa. Docker Engine 29 keeps this discipline hard: the daemon now requires API version v1.44 or later, and the client dropped support for negotiating versions below v1.44 — old enough that tooling has years of runway to migrate.<ref>{{#cite:Q1411}}</ref> Breaking changes are announced in the release notes and take effect per API version, not per install.<ref>{{#cite:Q1411}}</ref>

=== Standardize the primitives, assemble the rest ===

The most consequential decision is arguably the unbundling. Rather than keeping the whole stack proprietary to Docker, the low-level pieces became open standards and neutral projects:

* '''OCI (2015)''' — runtime, image and distribution specifications, with Docker's runc as the reference runtime. Any OCI-compliant engine can run OCI images; that is why <code>docker pull</code> images run under other runtimes.<ref>{{#cite:Q1418}}</ref>
* '''containerd (2016)''' — the core runtime spun out and donated to the CNCF, as part of "a multi-year effort to break up the Docker platform into a more modular architecture of loosely coupled components".<ref>{{#cite:Q1416}}</ref>
* '''Moby (2017)''' — the open-source framework of components and assemblies on which Docker itself is built, letting others assemble their own container systems from the same parts.<ref>{{#cite:Q1415}}</ref>

Docker Engine is thus best understood as one particular assembly of standardized, swappable components — "batteries included", but with every battery standardized and replaceable. Compose followed the same arc: born in 2014 as a Python tool (<code>docker-compose</code>), rewritten in Go as Compose v2 (2020) integrated into the CLI as <code>docker compose</code>, and released as Compose v5 (2025) with an official Go SDK — all defined by the rolling, version-less '''Compose Specification'''.<ref>{{#cite:Q1414}}</ref>

== Try it yourself ==

The commands below follow Docker's official documentation, verified on 2026-08-31. No Docker daemon was available in the authoring environment, so run them on your own machine with Docker installed; the outputs shown are those documented by Docker.

<syntaxhighlight lang="bash" copy>
# 1. Confirm the welcome-to-docker image really exists on Docker Hub (live check, 2026-08-31)
curl -s "https://hub.docker.com/v2/repositories/docker/welcome-to-docker/" | grep -o '"pull_count":[0-9]*'
</syntaxhighlight>

Output (verified live):

<syntaxhighlight lang="text" copy>
"pull_count":6104168
</syntaxhighlight>

<syntaxhighlight lang="bash" copy>
# 2. Start a web server container, publishing port 8080 on the host to port 80 in the container
docker run -d -p 8080:80 docker/welcome-to-docker
</syntaxhighlight>

"The output from this command is the full container ID."<ref>{{#cite:Q1408}}</ref> The container now serves a small website at http://localhost:8080.

<syntaxhighlight lang="bash" copy>
# 3. List running containers
docker ps
</syntaxhighlight>

Documented output (IDs and names vary):<ref>{{#cite:Q1408}}</ref>

<syntaxhighlight lang="text" copy>
CONTAINER ID   IMAGE                      COMMAND                  CREATED          STATUS          PORTS                      NAMES
a1f7a4bb3a27   docker/welcome-to-docker   "/docker-entrypoint.…"   11 seconds ago   Up 11 seconds   0.0.0.0:8080->80/tcp       gracious_keldysh
</syntaxhighlight>

<syntaxhighlight lang="bash" copy>
# 4. Stop the container
docker stop a1f7a4bb3a27
</syntaxhighlight>

"Only enough of the ID to make it unique" is needed — <code>docker stop a1f</code> would do.<ref>{{#cite:Q1408}}</ref>

<syntaxhighlight lang="bash" copy>
# 5. Run an interactive Ubuntu shell in a container
docker run -i -t ubuntu /bin/bash
</syntaxhighlight>

If the image isn't local, Docker pulls it; then it creates the container, allocates its writable layer, attaches it to the default network, starts it and runs <code>/bin/bash</code> — type <code>exit</code> and the container stops but is not removed.<ref>{{#cite:Q1407}}</ref>

<syntaxhighlight lang="bash" copy>
# 6. Build your own image from a Dockerfile
# Dockerfile:
#   FROM ubuntu
#   RUN apt-get update && apt-get install -y curl
#   COPY app.sh /app.sh
#   CMD ["/app.sh"]
docker build -t myapp .
</syntaxhighlight>

Docker reads the Dockerfile's instructions in order; each creates a layer, and unchanged layers are reused from the build cache on the next build.<ref>{{#cite:Q1410}}</ref><ref>{{#cite:Q1407}}</ref>

== References ==

<references/>

== Further reading ==

* [https://docs.docker.com/get-started/docker-overview/ What is Docker?] — the official overview
* [https://docs.docker.com/engine/ Docker Engine] — engine documentation
* [https://docs.docker.com/reference/dockerfile/ Dockerfile reference] — the build language
* [https://docs.docker.com/build/buildkit/ BuildKit] — the builder backend
* [https://docs.docker.com/compose/ Docker Compose] — multi-container applications
* [https://containerd.io/ containerd] — the container runtime
* [https://opencontainers.org/ Open Container Initiative] — the container standards
* [https://mobyproject.org/ Moby Project] — the open framework behind Docker
* [https://github.com/moby/moby moby/moby] — the engine's source code