Docker Architecture Explained: Complete End-to-End Flow (Images, Containers, Engine)

#!/bin/bash
# Trace the complete Docker architecture flow

# ── 1. CLI -> Daemon communication ───────────────────────────────────────────
# The CLI sends HTTP requests to the daemon socket
curl --unix-socket /var/run/docker.sock http://localhost/version | python3 -m json.tool
# Shows: Version, ApiVersion, GoVersion, Os, Arch, KernelVersion

# List containers via the API (same as docker ps)
curl --unix-socket /var/run/docker.sock http://localhost/containers/json | python3 -m json.tool

# ── 2. Daemon -> containerd communication ────────────────────────────────────
# containerd runs as a separate process, communicating via gRPC
ps aux | grep containerd
# root  1234  0.3  0.5  ... /usr/bin/containerd

# Check the containerd socket
ls -la /run/containerd/containerd.sock
# srw-rw---- 1 root containerd /run/containerd/containerd.sock

# List containers managed by containerd (via ctr)
sudo ctr -n moby containers ls
# Shows containers that containerd is managing on behalf of Docker

# ── 3. containerd -> runc communication ──────────────────────────────────────
# runc is invoked by containerd to create each container
which runc
# /usr/bin/runc

runc --version
# runc version 1.1.9

# List containers managed by runc
sudo runc list
# Shows: container ID, PID, status, bundle path

# ── 4. Inspect the OCI runtime spec for a running container ──────────────────
CONTAINER_ID=$(docker ps -q | head -1)

# Find the container's bundle directory
sudo find /run/containerd -name config.json 2>/dev/null | head -3
# /run/containerd/io.containerd.runtime.v2.task/default/<id>/config.json

# ── 5. Check the daemon process tree ─────────────────────────────────────────
pstree -p $(pidof dockerd)
# dockerd(1234)───containerd(1235)───containerd-shim(5678)───node(5679)
#                                                           └─pause(5677)

# ── 6. Check all components are running ──────────────────────────────────────
echo "dockerd: $(systemctl is-active docker)"
echo "containerd: $(systemctl is-active containerd)"
echo "runc: $(which runc && echo 'installed' || echo 'missing')"

# ── 7. Check the daemon's storage driver and root directory ──────────────────
docker info --format '{{.Driver}} {{.DockerRootDir}}'
# overlay2 /var/lib/docker

# ── 8. Check the daemon's configured runtimes ────────────────────────────────
docker info --format '{{json .Runtimes}}' | python3 -m json.tool
# Shows: runc (default), and any custom runtimes (runsc, kata)

#!/bin/bash
# Trace the complete image build flow

# ── 1. Build context size (before and after .dockerignore) ───────────────────
# Without .dockerignore:
tar -cf - . | wc -c
# May be 500MB+ if node_modules and .git are included

# With .dockerignore:
cat .dockerignore
# node_modules/
# .git/
# *.log

tar -cf - --exclude-from=.dockerignore . | wc -c
# Should be <10MB for a typical project

# ── 2. Build with cache inspection ───────────────────────────────────────────
# Build with BuildKit and progress=plain to see every step
DOCKER_BUILDKIT=1 docker build --progress=plain -t io.thecodeforge/api:1.0 . 2>&1 | tee /tmp/build.log

# Count cached vs executed steps:
grep -c 'CACHED' /tmp/build.log
grep -c 'RUN\|COPY' /tmp/build.log

# ── 3. Inspect the image layers ──────────────────────────────────────────────
# List layers in the image
docker inspect io.thecodeforge/api:1.0 --format '{{json .RootFS.Layers}}' | python3 -m json.tool
# Each entry is a SHA256 digest of a layer

# Show layer sizes
docker history io.thecodeforge/api:1.0 --format '{{.Size}}\t{{.CreatedBy}}' | head -10
# Shows the size contribution of each instruction

# ── 4. Find layers on disk ───────────────────────────────────────────────────
ls /var/lib/docker/overlay2/ | head -10
# Each directory is a layer. Shared layers are hard-linked.

# Check disk usage per layer:
du -sh /var/lib/docker/overlay2/* | sort -hr | head -10

# ── 5. Inspect the image manifest ────────────────────────────────────────────
# Save the image and inspect its manifest
docker save io.thecodeforge/api:1.0 | tar -xO manifest.json | python3 -m json.tool
# Shows: Config (image config), RepoTags, Layers (ordered list of layer tar files)

# ── 6. Compare BuildKit vs legacy builder performance ────────────────────────
# Legacy builder:
time DOCKER_BUILDKIT=0 docker build -t test:legacy .
# Sequential execution — slower for multi-step builds

# BuildKit:
time DOCKER_BUILDKIT=1 docker build -t test:buildkit .
# Parallel execution — faster for independent steps

# ── 7. Check the build cache ─────────────────────────────────────────────────
docker builder du
# Shows disk usage of the build cache

docker builder prune
# Removes unused build cache entries

#!/bin/bash
# Trace the image distribution flow

# ── 1. Inspect the local image manifest ──────────────────────────────────────
# Save the image and extract the manifest
docker save io.thecodeforge/api:1.0 -o /tmp/api-image.tar
cd /tmp && tar xf api-image.tar

# The manifest.json lists all components:
cat manifest.json | python3 -m json.tool
# [
#   {
#     "Config": "sha256:abc123...json",      <- image config
#     "RepoTags": ["io.thecodeforge/api:1.0"],
#     "Layers": [                              <- ordered layer list
#       "sha256:def456.../layer.tar",
#       "sha256:ghi789.../layer.tar"
#     ]
#   }
# ]

# ── 2. Inspect the image config ──────────────────────────────────────────────
cat sha256:abc123*.json | python3 -m json.tool | head -30
# Shows: architecture, os, config (env, cmd, entrypoint), rootfs (diff_ids)

# ── 3. Push to a registry ────────────────────────────────────────────────────
# Login to Docker Hub
docker login

# Tag the image for the registry
docker tag io.thecodeforge/api:1.0 youruser/io-thecodeforge-api:1.0

# Push — watch which layers are pushed vs already exist
docker push youruser/io-thecodeforge-api:1.0
# Output shows:
# Layer already exists (shared with base image)
# Pushing layer (unique to this image)

# ── 4. Pull from a registry ──────────────────────────────────────────────────
# Pull on a different machine
docker pull youruser/io-thecodeforge-api:1.0
# Output shows:
# Already exists (layers shared with local images)
# Downloading (unique layers)

# ── 5. Check pull-rate limit status ──────────────────────────────────────────
curl -s -I \
  -H "Authorization: Bearer $(curl -s 'https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull' | python3 -c 'import sys,json; print(json.load(sys.stdin)["token"])')" \
  https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest \
  | grep -i ratelimit
# ratelimit-limit: 100;w=21600
# ratelimit-remaining: 76;w=21600

# ── 6. Enable Docker Content Trust ───────────────────────────────────────────
export DOCKER_CONTENT_TRUST=1

# Now docker pull only fetches signed images
docker pull youruser/io-thecodeforge-api:1.0
# If the image is not signed, the pull fails with a trust error

# ── 7. Check layer deduplication ─────────────────────────────────────────────
# Compare layers between two images
docker inspect node:20-alpine --format '{{.RootFS.Layers}}' | tr ' ' '\n' | wc -l
docker inspect io.thecodeforge/api:1.0 --format '{{.RootFS.Layers}}' | tr ' ' '\n' | wc -l
# The API image shares base layers with node:20-alpine

#!/bin/bash
# Trace the complete container creation flow

# ── 1. Create a container (without starting it) ─────────────────────────────
docker create --name flow-demo \
  --cpus=1.0 \
  --memory=256m \
  -p 8080:3000 \
  -v demo-data:/app/data \
  alpine:3.19 sleep 3600

# ── 2. Inspect the container metadata ────────────────────────────────────────
# Container config stored by the daemon:
ls /var/lib/docker/containers/$(docker inspect flow-demo --format '{{.Id}}')/
# config.v2.json  hostconfig.json  hostname  hosts  resolv.conf  ...

# ── 3. Start the container and trace the flow ────────────────────────────────
docker start flow-demo

# Get the container's host PID:
CONTAINER_PID=$(docker inspect --format '{{.State.Pid}}' flow-demo)
echo "Container process PID on host: $CONTAINER_PID"

# ── 4. Inspect the OCI runtime spec ──────────────────────────────────────────
# Find the container's bundle in containerd's state:
sudo find /run/containerd -path '*flow-demo*' -name config.json 2>/dev/null

# Inspect the OCI spec (namespaces, mounts, process):
sudo cat /run/containerd/io.containerd.runtime.v2.task/default/*/config.json 2>/dev/null | python3 -m json.tool | head -60

# ── 5. Inspect the overlay2 filesystem ───────────────────────────────────────
docker inspect flow-demo --format '{{json .GraphDriver.Data}}' | python3 -m json.tool
# MergedDir: what the container sees as /
# UpperDir: writable layer (container-specific changes)
# LowerDir: read-only image layers

# ── 6. Inspect the network setup ─────────────────────────────────────────────
# Container's network config:
docker inspect flow-demo --format '{{json .NetworkSettings}}' | python3 -m json.tool | head -20
# Shows: IPAddress, Gateway, Ports, Networks

# veth pair on the host:
ip link show | grep veth
# vethXXXX@if4: <BROADCAST,MULTICAST,UP> ... master docker0

# iptables rules for port publishing:
sudo iptables -t nat -L -n | grep 8080
# DNAT rule forwarding host:8080 to container:3000

# ── 7. Find the pause process ────────────────────────────────────────────────
ps aux | grep pause | grep -v grep
# root  5677  0.0  0.0  1024  4  ?  Ss  10:23  0:00 /pause

# The pause process and container process share namespaces:
ls -la /proc/$CONTAINER_PID/ns/net
ls -la /proc/$(pgrep -f '/pause' | head -1)/ns/net
# Both point to the same namespace inode

# ── Cleanup ──────────────────────────────────────────────────────────────────
docker rm -f flow-demo

#!/bin/bash
# Inspect the complete Docker storage architecture

# ── 1. Check the storage driver ──────────────────────────────────────────────
docker info --format '{{.Driver}}'
# overlay2 (default on modern Linux)

# ── 2. Inspect the overlay2 directory structure ──────────────────────────────
ls /var/lib/docker/overlay2/ | head -10
# Each directory is a layer (image or container writable layer)

# Each layer directory contains:
ls /var/lib/docker/overlay2/<layer-hash>/
# diff/   — the actual filesystem content (only files that changed)
# link    — short name for the layer (used for path length limits)
# lower   — references to parent layers
# merged/ — the combined view (only for container layers)
# work/   — overlay2 internal working directory

# ── 3. Compare container vs image layers ─────────────────────────────────────
# Image layers are read-only and shared:
IMAGE_LAYERS=$(docker inspect alpine:3.19 --format '{{.RootFS.Layers}}')
echo "Image has $(echo $IMAGE_LAYERS | tr ' ' '\n' | wc -l) layers"

# Container adds one writable layer:
docker create --name storage-test alpine:3.19 sleep 3600
CONTAINER_UPPER=$(docker inspect storage-test --format '{{.GraphDriver.Data.UpperDir}}')
echo "Container writable layer: $CONTAINER_UPPER"

# ── 4. Demonstrate layer sharing between containers ──────────────────────────
# Create two containers from the same image
docker create --name storage-a alpine:3.19 sleep 3600
docker create --name storage-b alpine:3.19 sleep 3600

# Compare their lower layers (should be identical):
LOWER_A=$(docker inspect storage-a --format '{{.GraphDriver.Data.LowerDir}}')
LOWER_B=$(docker inspect storage-b --format '{{.GraphDriver.Data.LowerDir}}')
echo "Container A lower: $LOWER_A"
echo "Container B lower: $LOWER_B"
# Same layers — shared, not duplicated

# Compare their upper layers (should be different):
UPPER_A=$(docker inspect storage-a --format '{{.GraphDriver.Data.UpperDir}}')
UPPER_B=$(docker inspect storage-b --format '{{.GraphDriver.Data.UpperDir}}')
echo "Container A upper: $UPPER_A"
echo "Container B upper: $UPPER_B"
# Different directories — each container has its own writable layer

# ── 5. Inspect volumes ───────────────────────────────────────────────────────
docker volume create demo-volume

# Volume location on host:
docker volume inspect demo-volume --format '{{.Mountpoint}}'
# /var/lib/docker/volumes/demo-volume/_data

# Volumes bypass overlay2 — direct host filesystem access:
docker run --rm -v demo-volume:/data alpine:3.19 sh -c 'echo hello > /data/test'
cat /var/lib/docker/volumes/demo-volume/_data/test
# hello — directly accessible on the host

# ── 6. Compare performance: overlay2 vs volume vs bind mount ─────────────────
# overlay2 write (container writable layer):
time docker run --rm alpine:3.19 sh -c 'dd if=/dev/zero of=/tmp/test bs=1M count=100'
# ~0.3s

# Volume write:
time docker run --rm -v demo-volume:/data alpine:3.19 sh -c 'dd if=/dev/zero of=/data/test bs=1M count=100'
# ~0.2s (slightly faster — no overlay2 overhead)

# Bind mount write:
time docker run --rm -v $(pwd):/data alpine:3.19 sh -c 'dd if=/dev/zero of=/data/test bs=1M count=100'
# ~0.2s (direct host filesystem)

# ── Cleanup ──────────────────────────────────────────────────────────────────
docker rm -f storage-test storage-a storage-b
docker volume rm demo-volume

#!/bin/bash
# Inspect the complete Docker network architecture

# ── 1. Check the Docker bridge ───────────────────────────────────────────────
ip addr show docker0
# docker0: <BROADCAST,MULTICAST,UP> mtu 1500
#     inet 172.17.0.1/16
# The bridge has the gateway IP for the container subnet

# ── 2. Create a container and inspect its veth pair ──────────────────────────
docker run -d --name net-demo alpine:3.19 sleep 3600

# Get the container's host PID:
CONTAINER_PID=$(docker inspect --format '{{.State.Pid}}' net-demo)

# Inside the container, see eth0 (one end of the veth pair):
docker exec net-demo ip addr show eth0
# eth0@if7: <BROADCAST,MULTICAST,UP> mtu 1500
#     inet 172.17.0.2/16

# On the host, see the other end of the veth pair:
ip link show | grep veth
# vethXXXX@if4: <BROADCAST,MULTICAST,UP> ... master docker0
# The host end is attached to the docker0 bridge

# ── 3. Inspect iptables rules ────────────────────────────────────────────────

# NAT rules for port publishing:
sudo iptables -t nat -L DOCKER -n -v
# DNAT  tcp  --  anywhere  anywhere  tcp dpt:8080 to:172.17.0.2:3000

# Forward rules:
sudo iptables -L DOCKER -n -v
# ACCEPT  tcp  --  anywhere  172.17.0.2  tcp dpt:3000

# MASQUERADE for outbound traffic:
sudo iptables -t nat -L POSTROUTING -n -v | grep 172.17
# MASQUERADE  all  --  172.17.0.0/16  !172.17.0.0/16

# ── 4. Check DNS resolution (default vs user-defined network) ────────────────

# Default bridge — no DNS:
docker exec net-demo cat /etc/resolv.conf
# nameserver 8.8.8.8 (host's DNS, not container-specific)
docker exec net-demo nslookup other-container
# Fails — no embedded DNS on default bridge

# User-defined network — embedded DNS:
docker network create app-net
docker run -d --name api --network app-net alpine:3.19 sleep 3600
docker run -d --name db --network app-net alpine:3.19 sleep 3600

docker exec api cat /etc/resolv.conf
# nameserver 127.0.0.11 (embedded DNS server)
docker exec api nslookup db
# Name: db  Address: 172.18.0.3

# ── 5. Inspect network configuration ─────────────────────────────────────────
docker network inspect bridge --format '{{json .IPAM.Config}}' | python3 -m json.tool
# [{"Subnet": "172.17.0.0/16", "Gateway": "172.17.0.1"}]

docker network inspect app-net --format '{{json .IPAM.Config}}' | python3 -m json.tool
# [{"Subnet": "172.18.0.0/16", "Gateway": "172.18.0.1"}]

# ── 6. Trace network traffic ─────────────────────────────────────────────────
# Capture packets on the docker0 bridge:
sudo tcpdump -i docker0 -n -c 10
# Shows ARP requests, TCP SYN packets between containers

# Capture packets inside a container:
sudo nsenter --net --target $CONTAINER_PID tcpdump -i eth0 -n -c 10

# ── Cleanup ──────────────────────────────────────────────────────────────────
docker rm -f net-demo api db
docker network rm app-net