Dev.to WebDev 🛠 Dev 👁 0 📖 10 min read

How Docker Works Under the Hood: From Docker CLI to runc | Mahdi Shamlou

Hey everyone! Mahdi Shamlou here! Today, I want to talk about something interesting: How Docker actually works behind the scenes. Most of us use Docker every day. We write Dockerfiles, build images, create container

How Docker Works Under the Hood: From Docker CLI to runc | Mahdi Shamlou

Hey everyone! Mahdi Shamlou here!

Today, I want to talk about something interesting: How Docker actually works behind the scenes.

Mahdi Shamlou

Most of us use Docker every day.

We write Dockerfiles, build images, create containers, and manage them using Docker commands.

But have you ever wondered what actually happens when you execute this command?

docker run nginx

How does Docker understand this command?

Which component receives it?

Who creates the container?

How does Docker prepare the container's filesystem?

And how does a simple command eventually become a running Linux process?

In this article, I want to explain Docker's internal architecture, starting from the Docker CLI and going all the way down to runc.

We will explore each component step by step.

Let's get started!

1. Understanding Docker Architecture

First, let's look at the big picture.

Docker uses a client-server architecture.

This means that Docker has different components responsible for different tasks.

Here are the main components we are going to discuss:

  1. Docker CLI
  2. Docker API
  3. Docker Daemon (dockerd)
  4. containerd
  5. Snapshotters
  6. Container Filesystem
  7. containerd-shim
  8. runc
  9. Linux Kernel

Let's look at how they communicate.

flowchart TD
    A["User"] --> B["Docker CLI"]
    B --> C["Docker API"]
    C --> D["Docker Daemon (dockerd)"]
    D --> E["containerd"]

    E --> F["Snapshotter"]
    F --> G["Container Filesystem"]

    E --> H["containerd-shim"]
    H --> I["runc"]
    I --> J["Linux Kernel"]
    J --> K["Container Process"]

Each component has a different responsibility.

The important thing to understand is that Docker CLI does not directly create containers.

It sends requests to other components, and each component handles a specific part of the process.

Let's understand them individually.

2. Docker CLI

The Docker CLI is the command-line interface that we use to communicate with Docker.

Mahdi Shamlou

Whenever we execute commands such as:

docker run nginx
docker ps
docker images
docker stop my-container
docker build .

We are using the Docker CLI.

Its main responsibility is to provide an interface between the user and Docker Engine.

For example, when we execute:

docker run nginx

The CLI does not create a container itself.

Instead, it converts our command into an API request and sends it to the Docker Daemon.

We will discuss that communication in the next section.

You can think of Docker CLI as the interface that allows us to control Docker without interacting with its internal components directly.

Official documentation:

3. Docker API

Now we know that Docker CLI sends requests to Docker Daemon.

But how do these components communicate?

The answer is the Docker API.

Docker provides an API that allows different applications to communicate with Docker Engine.

The communication usually happens through a Unix socket:

/var/run/docker.sock

For example:

Docker CLI
    |
    | HTTP API Request
    |
    v
/var/run/docker.sock
    |
    v
Docker Daemon

The Docker API is not limited to the CLI.

Other applications can also communicate with Docker using this API.

For example:

  • Docker Compose
  • Docker SDK for Python
  • Docker SDK for Go
  • Other automation tools

This means we can control Docker programmatically without using terminal commands.

One important detail:

Docker can also communicate over a network connection, which allows a Docker CLI to control a remote Docker Daemon.

Official documentation:

4. Docker Daemon (dockerd)

Now we reach one of the most important components: Docker Daemon.

The Docker Daemon is a background process responsible for managing Docker resources.

Its executable name is:

dockerd

You can check its status on Linux using:

systemctl status docker

Or inspect the process:

ps aux | grep dockerd

But what exactly does Docker Daemon manage?

Some of its responsibilities include:

  • Managing containers
  • Managing images
  • Managing networks
  • Managing volumes
  • Managing Docker-related operations
  • Communicating with containerd

For example, when we execute:

docker run nginx

Docker Daemon receives the request and starts coordinating the operations needed to create and start the container.

It also checks whether the required image is available locally.

If the image does not exist, Docker can pull it from a registry.

After that, it coordinates container creation and delegates container lifecycle operations to containerd.

However, Docker Daemon does not directly handle all the low-level container operations.

For that, it uses another component called containerd.

Official documentation:

5. containerd

Now we are getting closer to the actual container creation process.

containerd is a container runtime responsible for managing the container lifecycle.

It is a separate open-source project and is also used by other container platforms.

Its responsibilities include:

  • Managing container lifecycle
  • Managing image content
  • Managing filesystem snapshots
  • Starting and stopping containers
  • Communicating with container runtime shims

Let's look at a simple example.

When Docker Daemon receives a request to create a container, it delegates the required container lifecycle operations to containerd.

containerd then prepares the necessary resources and coordinates the creation and execution of the container.

But containerd does not directly create all Linux isolation features itself.

It uses another component called containerd-shim, which works with a low-level runtime such as runc.

containerd also uses a storage component called snapshotters.

Snapshotters are responsible for preparing and managing the filesystem snapshots used by containers.

We will explore this in more detail in the next section.

Official documentation:

6. Snapshotters

Now let's explore an important part of container storage: snapshotters.

You might already know that Docker images are built using multiple layers.

For example, an image might contain:

Application Layer
Python Dependencies Layer
Python Runtime Layer
Base OS Layer

Each layer represents a set of filesystem changes.

But how does containerd prepare these layers so that a container can use them?

This is where snapshotters come in.

A snapshotter is a component of containerd responsible for managing filesystem snapshots.

It prepares the filesystem that a container will use.

How does a snapshotter work?

Let's imagine we have an image with three layers:

Layer 3: Application Files
Layer 2: Dependencies
Layer 1: Base Filesystem

These layers are stored as image content.

A snapshotter prepares snapshots from these layers so they can be used as a filesystem.

When a container is created, the snapshotter can prepare a writable snapshot on top of the image's read-only layers.

A simplified view looks like this:

              Container Image
                     |
          +----------+----------+
          |          |          |
       Layer 1    Layer 2    Layer 3
          |          |          |
          +----------+----------+
                     |
                     v
                Snapshotter
                     |
                     v
             Container Filesystem

What is the difference between a snapshotter and a storage driver?

In older Docker storage architectures, Docker used storage drivers such as overlay2.

With the containerd image store, containerd uses snapshotters instead.

For example:

  • overlayfs: Uses Linux OverlayFS to manage filesystem layers.
  • Other snapshotters can support different storage backends and features.

The important thing to understand is that snapshotters provide the storage mechanism used to prepare container filesystems.

The exact storage architecture depends on your Docker version and configuration.

Official documentation:

7. Container Filesystem

Now that we understand snapshotters, let's look at the filesystem inside a container.

When we start a container, Docker provides it with a filesystem.

This filesystem is usually based on the image layers.

Let's use a simple example.

Imagine we have an Nginx image containing:

/
├── bin/
├── etc/
├── lib/
├── usr/
└── var/

When Docker creates a container from this image, it prepares a filesystem that the container process can use.

But there is something important here.

The image layers are read-only.

The container receives an additional writable layer on top of those image layers.

We can visualize it like this:

        Container Filesystem
        +-------------------+
        | Writable Layer    |
        +-------------------+
        | Image Layer 3     |
        +-------------------+
        | Image Layer 2     |
        +-------------------+
        | Image Layer 1     |
        +-------------------+

Why do we need a writable layer?

Imagine that Nginx writes a log file or your application creates a temporary file.

These changes should not modify the original image.

Instead, Docker stores them in the container's writable layer.

This allows multiple containers to use the same image while keeping their filesystem changes separate.

For example:

              nginx:latest
                   |
          +--------+--------+
          |                 |
          v                 v
      Container A       Container B
          |                 |
     Writable Layer    Writable Layer
          |                 |
        File A             File B

Both containers use the same image layers, but each one has its own writable layer.

One important detail:

Data stored only in the container's writable layer is removed when the container is removed.

If we need persistent data, we should use persistent storage such as Docker volumes.

Official documentation:

8. containerd-shim

This is one of the most interesting components in Docker architecture.

You might wonder:

Why do we need another component between containerd and runc?

The answer is process management and lifecycle management.

containerd-shim acts as an intermediate process between containerd and the low-level runtime.

Its responsibilities include:

  • Managing the container process.
  • Keeping the container running independently of the containerd daemon.
  • Handling communication with containerd.
  • Collecting the container's exit status.

Let's understand this with a simple example.

Imagine we have a running container.

What happens if containerd restarts?

We don't necessarily want all running containers to stop just because containerd has restarted.

The shim helps avoid this dependency.

It stays alive and manages the container process even if containerd is restarted.

Another important detail:

The shim is not the component that creates Linux namespaces and cgroups.

That responsibility belongs to the low-level runtime.

And in the default Docker configuration, that runtime is usually runc.

For the runc runtime, the commonly used shim implementation is:

containerd-shim-runc-v2

Official documentation:

9. runc

Finally, we reach runc!

runc is a low-level container runtime that implements the Open Container Initiative (OCI) Runtime Specification.

Its main responsibility is to create and start containers using Linux kernel features.

But what does that actually mean?

Let's look at some of the things runc handles.

1. Namespaces

Namespaces provide isolation between containers and the host system.

For example:

  • PID Namespace: Isolates process IDs.
  • Network Namespace: Isolates network interfaces and routing tables.
  • Mount Namespace: Isolates filesystem mount points.
  • UTS Namespace: Isolates hostname and domain name.
  • IPC Namespace: Isolates inter-process communication.
  • User Namespace: Isolates user and group IDs.

2. cgroups

Control Groups (cgroups) allow Linux to control and monitor resource usage.

For example:

  • CPU limits
  • Memory limits
  • Process limits

3. Capabilities

Linux capabilities divide traditional root privileges into smaller permissions.

This allows a container to receive only the privileges it needs.

4. Filesystem Setup

runc also performs important filesystem operations, such as setting up the container's root filesystem and configuring mounts based on the runtime configuration.

5. Starting the Process

After configuring the required isolation and environment, runc starts the container's main process.

For example:

nginx

At this point, we have a running process inside an isolated environment.

One important thing to remember:

A container is not a virtual machine.

It is a normal Linux process running with isolation and resource restrictions provided by the Linux kernel.

Official documentation:

10. What Happens When We Execute docker run nginx?

Now that we understand the components, let's connect everything together.

Imagine we execute:

docker run -d --name my-nginx nginx

What happens behind the scenes?

Let's follow the process.

Step 1: Docker CLI

Docker CLI receives our command.

It understands that we want to create and start a container using the Nginx image.

Step 2: Docker API

The CLI sends an API request to Docker Daemon.

Usually, this communication happens through:

/var/run/docker.sock

Step 3: Docker Daemon

Docker Daemon receives the request.

It checks whether the Nginx image exists locally.

If it does not exist, Docker pulls it from the configured registry.

Then Docker coordinates the container creation process.

Step 4: containerd

Docker Daemon communicates with containerd.

containerd handles the required container lifecycle operations.

Step 5: Snapshotter and Filesystem

The snapshotter prepares the filesystem based on the image layers.

It also creates a writable snapshot for the container.

The result is a filesystem that the container process can use.

Step 6: containerd-shim

containerd starts the appropriate runtime shim.

The shim provides a process that can manage the container lifecycle and communicate with containerd.

Step 7: runc

The shim invokes runc.

runc configures the container environment using Linux kernel features such as:

  • Namespaces
  • cgroups
  • Capabilities
  • Mounts

Then it starts the container's main process.

Step 8: Linux Kernel

The Linux kernel provides the isolation and resource management mechanisms.

Finally, the Nginx process starts inside its isolated environment.

Here is a simplified view of the process:

sequenceDiagram
    participant U as User
    participant CLI as Docker CLI
    participant API as Docker API
    participant D as dockerd
    participant C as containerd
    participant S as Snapshotter
    participant SH as containerd-shim
    participant R as runc
    participant K as Linux Kernel

    U->>CLI: docker run -d nginx
    CLI->>API: Send API request
    API->>D: Forward request
    D->>C: Request container creation
    C->>S: Prepare filesystem snapshot
    S-->>C: Filesystem ready
    C->>SH: Start runtime shim
    SH->>R: Invoke runc
    R->>K: Configure container environment
    K-->>R: Environment configured
    R-->>SH: Container process started
    SH-->>C: Report container status
    C-->>D: Report container status
    D-->>CLI: Return container information
    CLI-->>U: Display container ID

Notice that runc is not responsible for managing the entire lifecycle of Docker.

Its main responsibility is to create and start the container process.

The shim and containerd handle the lifecycle management around it.

Final Thoughts

Mahdi Shamlou

Before learning Docker internals, I used to think that Docker was just a tool that created containers from images.

But after exploring its architecture, I realized that several components work together to make this process possible.

Understanding these components helps us debug problems, understand container lifecycle operations, and make better decisions when working with Docker in production.

I believe that understanding how our tools work internally is just as important as knowing how to use them.

What do you think? Which Docker component would you like to explore in more detail?

Let me know in the comments!

Author: Mahdi Shamlou

Author: مهدی شاملو

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.