The Complete Docker Guide

This is part one of three. It covers everything you need to do real work with Docker, not a teaser. By the end you can build an image, run and debug a container, keep data alive, wire two services together, and hand a colleague one command that starts your whole project. Mid-level and Senior take the same topics further; nothing here is thrown away.

Each section ends with a Try it task. Do them as you go. They take a few minutes each, and these concepts only stick once you have watched your own container start, crash, and start again properly.

What Docker is, and the problem it solves

Docker packages an application together with the environment it needs to run (the language runtime, the libraries, the system packages, the configuration) into a single file called an image. You can then run that image as a container on any machine that has Docker, and it behaves the same way.

The diagram is the whole idea. Compare it to what came before.

Before containers, getting a project running meant a page of setup instructions: install this version of Python, install these system libraries, set these environment variables, start Postgres, create a database. Every developer executed those steps slightly differently, so every developer's machine was slightly different. Then the server was different again (a different distribution, a different libc, an older OpenSSL) and code that passed every test locally failed in production for reasons nobody could reproduce.

"It works on my machine" describes a real, structural problem rather than a careless developer: the environment was never part of the thing you tested. Docker makes it part of the thing you ship.

Two consequences of that design explain most of what follows. Notice them now rather than discovering them later.

The environment is described in a file you commit. Your Dockerfile sits next to your source code, so it is versioned, branched, reviewed, and diffed like any other code. When the build breaks, git log tells you who changed the environment and why. This sounds administrative; in practice it is the single biggest reason teams stop being afraid of their deployment.

A container is disposable. You do not repair a container, you delete it and start a new one from the image. That is what makes containers safe to experiment with, and it is also the biggest source of confusion for newcomers, because anything you wrote inside the container disappears with it. We will come back to that repeatedly.

What people use it for:

You need little to follow along: Docker installed, a terminal, and any small project. A brand-new folder with a three-line web app is the best place to experiment, because a failed build costs you nothing.

Container versus virtual machine

This is the most common interview opener and the most common source of wrong mental models, so get it straight before anything else.

Keep this sentence: a container is a process on your machine with a restricted view of the filesystem, the network, and the process table. It is not a small computer. There is no second operating system booting inside it, which is why it starts in the time it takes to start any other program.

That restricted view is convincing enough to be confusing. Inside a container, ls / shows a different filesystem, ps aux shows only the container's own processes, and hostname returns something unfamiliar. None of that is emulation. The Linux kernel is showing that process a different picture. Senior level covers how, because the security consequences matter. For now, the practical takeaways are:

Image, container, registry: the three nouns

Three words that get used interchangeably in conversation and mean different things in practice.

docker run hello-world       # pulls the image from a registry, then runs a container

That one command exercises all three ideas: Docker looks for the hello-world image locally, does not find it, pulls it from Docker Hub, creates a container from it, runs it, and the container exits when its program finishes.

Check your setup: client, daemon, registry

Before writing anything, confirm what you have. Three commands tell you everything that matters.

docker version          # client and server versions — the server line is the daemon
docker info             # storage driver, root directory, resources, warnings
docker run hello-world  # end-to-end proof: pull, create, run

docker version printing a Client section but failing on Server is the single most common setup problem, and it has one meaning: the Docker daemon is not running. Start Docker Desktop, or on Linux sudo systemctl start docker.

Know the shape of what you just installed, because it explains several error messages:

The docker command you type is only a client. It sends your request over a socket to a background service, the daemon, which builds images, starts containers, and manages storage. This matters in three practical ways: the daemon needs to be running for any command to work, files are sent to the daemon at build time (which is why build context size affects speed), and on Linux the socket is root-owned, which is why Docker commands need sudo until your user is added to the docker group.

Your first containers

Now run something real. These six commands are the core loop of working with Docker, and you will type them thousands of times.

# 1. Run a web server in the background, mapped to localhost:8080
docker run -d -p 8080:80 --name web nginx

# 2. Confirm it is running
docker ps

# 3. Read what it is printing
docker logs web

# 4. Get a shell inside it and look around
docker exec -it web sh

# 5. Stop it
docker stop web

# 6. Delete it
docker rm web

Open http://localhost:8080 after the first command and nginx is serving a page, with nothing installed on your machine, no configuration file edited, and nothing to uninstall afterwards.

Read that first command flag by flag, because each one answers a question you will keep asking:

Without -d the container runs in the foreground and your terminal shows its output until you press Ctrl+C. That is often what you want while developing, and always what you want the first time you run something new. You get to see it fail.

The commands you will use, by verb

There are hundreds of Docker subcommands. In day-to-day work you use about fifteen.

The docker run flags worth memorising early:

Two of those deserve a note now because they save real time. docker exec -it NAME sh only works on a running container; if the container has already exited there is nothing to exec into, and you want --entrypoint sh instead. docker inspect is the answer to almost every "but I set that" argument. It shows the container's configuration after every default, image setting, and command-line override has been resolved.

The container lifecycle, state by state

A container moves through a small number of states, and most beginner confusion comes from not knowing which one it is in.

The rule that explains most surprises: a container lives as long as its main process. Not as long as you want it to, and not until you stop it. It lives as long as process number one inside it keeps running.

docker run ubuntu                 # exits immediately
docker run -it ubuntu bash        # stays, because bash has a terminal to read from
docker run -d nginx               # stays, because nginx is a server that does not exit
docker run --rm alpine echo hi    # prints "hi", exits, removes itself

An exited container still exists. Its filesystem, its logs, and its exit code are all still there, which is what you need in order to debug it, and it is why docker ps -a fills up with corpses if you never use --rm.

Images, tags, and registries

An image reference has three parts, and Docker fills in the ones you leave out, which is where surprises come from.

ghcr.io/my-org/myapp:1.4.2
└──┬──┘ └──┬───┘ └─┬─┘ └┬─┘
registry  owner   name  tag

docker pull nginx:1.27           # download without running
docker images                    # what you have locally
docker tag myapp:1.0 myuser/myapp:1.0
echo "$TOKEN" | docker login ghcr.io -u USERNAME --password-stdin
docker push myuser/myapp:1.0
docker rmi nginx:1.27            # delete a local image

Choosing a base image is your first real decision, and the sensible default is narrower than people expect:

Writing a Dockerfile

Running other people's images is useful. Building your own is the point.

A Dockerfile is a plain text file, named exactly that, describing how to construct an image. Each instruction takes the result of the previous one and adds something.

FROM python:3.11-slim          # the base image to start from

WORKDIR /app                   # cd into /app, creating it if needed

COPY requirements.txt .        # copy one file from your machine into the image
RUN pip install --no-cache-dir -r requirements.txt   # runs at BUILD time

COPY . .                       # now copy the rest of the source

EXPOSE 8000                    # documentation: this app listens on 8000

CMD ["python", "-m", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

docker build -t myapp:1.0 .    # the "." is the build context, not the Dockerfile
docker run -d -p 8000:8000 myapp:1.0

Let me walk through every line, because this small file contains the entire conceptual model.

FROM python:3.11-slim says "start from this image". You are never building from nothing; you are adding to something. This must be the first instruction.

WORKDIR /app sets the working directory for every instruction after it, and for the container at run time. It creates the directory if it does not exist, which is why you rarely need mkdir.

COPY requirements.txt . copies from the build context (your project folder) into the image at the current WORKDIR. Note it copies into the image, permanently. This is a build-time action, and the file is baked in.

RUN pip install … executes a command while building and saves the result as part of the image. The installed packages are now in the image forever. This is the instruction people misuse most, and the next section explains why.

COPY . . copies everything else. It comes after the install deliberately. That ordering is the single biggest speed lever available to you, and it has its own section below.

EXPOSE 8000 is documentation. It publishes nothing at all.

CMD [...] is the default command run when a container starts. It runs at run time, every time, never during the build.

The -t myapp:1.0 in the build command is the tag you are giving the result, in name:tag form. Skip it and you get an untagged image identified only by a hash, which is how "dangling" images accumulate.

The Dockerfile instructions worth knowing

There are about eighteen instructions. These are the ones that appear in real Dockerfiles.

Three of them are worth extra words now, because they are commonly confused.

COPY versus ADD. They look interchangeable. ADD additionally auto-extracts local tar archives and can download a URL, behaviour that is convenient once and surprising thereafter. Use COPY always, and reach for ADD only when you specifically want tar extraction.

ENV versus ARG. ARG exists only during the build; ENV persists into the running container. Both are visible to anyone who can pull the image, so neither is a place for a secret.

ARG PYTHON_VERSION=3.11        # build only; pass with --build-arg
FROM python:${PYTHON_VERSION}-slim

ENV LOG_LEVEL=info             # a default, present at run time and overridable with -e
ENV PYTHONUNBUFFERED=1         # makes Python flush stdout, so docker logs works properly

PYTHONUNBUFFERED=1 deserves a special mention. Python buffers stdout when it is not a terminal, so in a container your log lines can sit in a buffer for a long time and docker logs looks empty while the app is working. One ENV line removes an entire class of confusion.

LABEL costs nothing and answers "where did this image come from?" six months later:

LABEL org.opencontainers.image.source="https://github.com/my-org/myapp"
LABEL org.opencontainers.image.description="Checkout API"

Layers: why COPY order decides your build time

This is the single biggest speed lever a beginner can pull, and it takes one minute to apply.

Every instruction in a Dockerfile produces a layer, a record of what changed in the filesystem. An image is those layers stacked on top of each other, read-only. A container adds one thin writable layer on top of the stack.

Docker caches layers. When you rebuild, it walks the instructions from the top and reuses each layer whose inputs have not changed. The moment one layer is invalidated, every layer after it must be rebuilt.

Now the consequence. Your source code changes constantly; your dependency list barely ever changes. So the order of two instructions decides whether every build reinstalls all your dependencies:

The same reasoning applies inside a single RUN. Package manager metadata and cleanup must happen in the same instruction, because a later instruction cannot remove anything from an earlier layer:

# Wrong: the stale package index gets cached, and the lists stay in the image
RUN apt-get update
RUN apt-get install -y curl

# Right: one layer, cleaned up inside that same layer
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl \
 && rm -rf /var/lib/apt/lists/*

You can see the layers you built:

docker history myapp:1.0                  # every layer, its size, and the instruction
docker image inspect myapp:1.0 --format '{{.Size}}'

The build context and .dockerignore

When you run docker build -t myapp ., that trailing dot sets the build context rather than naming the Dockerfile: it is the directory that gets packaged up and sent to the Docker daemon before the build even starts.

That has two consequences people discover the hard way. First, it is slow if the folder is large: .git, node_modules, a virtualenv, build output, and datasets all get transferred. Second, and more seriously, anything in the context can end up in the image, including the .env file you never meant to ship.

.dockerignore fixes both. It sits next to your Dockerfile and uses the same syntax as .gitignore.

# Version control and tooling
.git
.gitignore
.github

# Dependencies — reinstalled inside the image
node_modules
__pycache__
*.pyc
.venv
venv

# Local configuration and secrets
.env
.env.*
*.pem
*.key

# Build output and noise
dist
build
*.log
coverage
.pytest_cache

# Editor and OS files
.vscode
.idea
.DS_Store

Write this before your first build, not after your first slow build. It is the cheapest file in your project.

CMD versus ENTRYPOINT

Both describe what runs when the container starts, and the difference between them is a favourite interview question because it reveals whether you have shipped an image.

# CMD only: the whole command is a default
CMD ["uvicorn", "app:app", "--host", "0.0.0.0"]
# docker run myapp                 → runs uvicorn
# docker run myapp python -V       → runs python -V instead

# ENTRYPOINT + CMD: fixed program, default arguments
ENTRYPOINT ["uvicorn", "app:app"]
CMD ["--host", "0.0.0.0", "--port", "8000"]
# docker run myapp                 → uvicorn app:app --host 0.0.0.0 --port 8000
# docker run myapp --port 9000     → uvicorn app:app --port 9000

The pairing in the second example is the pattern worth copying for a real service: ENTRYPOINT names the program, CMD supplies arguments a user might reasonably want to override.

There is a second, less obvious distinction that matters more than the first one: exec form versus shell form.

CMD ["node", "server.js"]     # exec form (a JSON array): your process is PID 1
CMD node server.js            # shell form: PID 1 is /bin/sh, which runs your process

--entrypoint on docker run overrides ENTRYPOINT, which is the single most useful debugging flag in Docker:

docker run -it --entrypoint sh myapp:1.0     # skip the app, get a shell, look around

Ports and publishing

A container has its own network namespace, which means its ports are its own. Nothing on your machine can reach them until you publish one.

docker run -d -p 8080:80 nginx            # localhost:8080 → container port 80
docker run -d -p 3000:3000 myapp          # same port on both sides
docker run -d -p 127.0.0.1:8080:80 nginx  # only reachable from this machine
docker run -d -P nginx                    # publish every EXPOSEd port to random host ports
docker port web                            # what is actually mapped

The order is host first, container second. Getting it backwards is a classic, and the error it produces is not obvious. You get a container that appears to run but refuses connections.

Two rules cover almost every port problem you will hit:

Inside a container, your app must listen on 0.0.0.0. Not 127.0.0.1, and not localhost. Binding to loopback inside a container means "reachable only from inside this container", so -p appears to do nothing at all. Most frameworks default to loopback, which is why nearly every containerised app command has a --host 0.0.0.0 in it.

One host port can only be used once. bind: address already in use means something else, often a previous container you forgot to remove, already has it. docker ps then docker rm -f clears it.

Configuration: environment variables and files

An image should be built once and then run in development, staging, and production without modification. That only works if everything environment-specific arrives at run time.

docker run -e LOG_LEVEL=debug -e DATABASE_URL="$DB_URL" myapp:1.0
docker run --env-file ./local.env myapp:1.0
docker run --rm myapp:1.0 env                  # see what the container actually got

LOG_LEVEL=debug
DATABASE_URL=postgres://postgres:secret@db:5432/app
FEATURE_NEW_CHECKOUT=true

The mechanisms and where each one belongs:

Precedence, most specific first: -e on the command line beats --env-file, which beats ENV in the Dockerfile. That layering is what makes one image work everywhere.

Logs, and getting inside a container

Two commands cover almost all day-to-day investigation.

docker logs web                  # everything the container has printed
docker logs -f --tail 50 web     # follow, starting from the last 50 lines
docker logs --since 10m web      # only the last ten minutes
docker logs -t web               # with timestamps

docker exec -it web sh           # a shell inside a RUNNING container
docker exec web env              # run one command without a shell session
docker exec -u root -it web sh   # as root, when you need to install a debug tool

docker logs reads whatever the container's main process wrote to stdout and stderr. That is the whole mechanism, and it has one important implication: if your app writes to a log file inside the container instead, docker logs shows nothing and your logs die with the container.

Three more commands complete the toolkit:

docker inspect web               # resolved config: entrypoint, env, mounts, network, state
docker stats                     # live CPU and memory, per container
docker cp web:/etc/nginx/nginx.conf ./     # copy a file out to look at it properly

Keeping data: volumes

Delete a container and its writable layer goes with it. Anything you want to survive must live in a volume.

# Named volume — Docker manages the storage. Right for databases and app state.
docker run -d --name db \
  -e POSTGRES_PASSWORD=secret \
  -v pgdata:/var/lib/postgresql/data \
  postgres:16

# Bind mount — a real folder on your machine. Right for live-reload development.
docker run -d -p 8000:8000 -v "$(pwd)":/app myapp:dev

# Read-only mount, for configuration the container must not change
docker run -d -v ./config.yaml:/etc/app/config.yaml:ro myapp:1.0

docker volume ls
docker volume inspect pgdata
docker volume rm pgdata          # only works if no container is using it

A named volume is storage Docker created and manages, referenced by a name; a bind mount is a path on your machine grafted into the container. That difference decides real outcomes. Named volumes survive docker rm, move with your project, and get sensible permissions. Bind mounts are for when you want the host's actual files, chiefly so your editor and the container see the same source code.

Networking: how containers find each other

One container is rarely enough. As soon as you have an app and a database, they need to talk, and the way they find each other surprises everyone once.

docker network create appnet

docker run -d --name db  --network appnet -e POSTGRES_PASSWORD=secret postgres:16
docker run -d --name api --network appnet -p 8000:8000 \
  -e DATABASE_URL=postgres://postgres:secret@db:5432/postgres myapp:1.0

The connection string says db, not localhost. On a network you created, Docker runs a DNS server and every container is reachable by its name. That is the whole mechanism.

The important row is the first two. If you never create a network, your containers land on the default bridge, where names do not resolve and you are left using IP addresses. Creating a network is one command and it is why Compose, which does it for you, feels so much easier.

Do not run as root

By default the process inside a container runs as root. Adding a user is two lines and it is the highest-value security change available to a beginner.

FROM python:3.11-slim

# Create a real user with a fixed numeric id
RUN useradd --create-home --uid 10001 appuser

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Give the app's files to that user as they are copied
COPY --chown=appuser:appuser . .

USER 10001                     # everything after this runs unprivileged

EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Two details in there are deliberate. USER comes after the installs, because pip install into system directories needs the privileges you are about to drop. The id is numeric rather than a name, because that form is unambiguous to tooling and to orchestrators.

Order matters, and getting it wrong produces permission errors that look mysterious:

Docker Compose: many containers, one file

By now a single docker run line has six flags on it, and you have two containers plus a network to start in the right order. That is what Compose is for: it moves everything you were typing into a file you commit.

services:
  api:
    build: .                                # build from the Dockerfile here
    ports: ['8000:8000']
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/app
      LOG_LEVEL: debug
    depends_on: [db]
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes: ['pgdata:/var/lib/postgresql/data']

volumes:
  pgdata:

docker compose up -d          # build if needed, create the network, start everything
docker compose ps             # what is running, and its health
docker compose logs -f api    # follow one service
docker compose exec api sh    # a shell in a service
docker compose down           # stop and remove containers and the network
docker compose down -v        # …and delete the named volumes too

Every key in that file maps to something you already know:

Two things Compose gives you for free are worth calling out. It creates a network and puts every service on it, so api reaches the database at the hostname db with no configuration at all. It makes the whole stack one unit: up, down, logs, and ps operate on all of it.

Debugging a container that will not start

This is the skill everything else depends on, and it has an order. Work down the list rather than guessing.

1. Read the logsdocker logs NAME. An exited container keeps its output until you remove it, so this works even after a crash. Most failures explain themselves here and you can stop at step one.
2. Check the exit codedocker ps -a shows it in the STATUS column. 0 = finished normally · 1 = application error · 125 = bad docker run flags · 126 = command not executable · 127 = command not found · 137 = killed, usually out of memory · 143 = stopped by SIGTERM.
3. Override the entrypoint and look arounddocker run -it --entrypoint sh myapp:1.0 starts the image without running your app, so you can inspect it and try the command by hand.
4. Check the file is where you think it isInside that shell: pwd, ls -la, cat the config. A wrong WORKDIR or a file excluded by .dockerignore explains most "not found" errors.
5. Run the command manuallyType the exact CMD yourself in that shell. The error message you get interactively is usually far more informative than the one in the logs.
6. Inspect the resolved configurationdocker inspect NAME shows the real entrypoint, command, environment, mounts, and networks after every default and override has been applied. This settles "but I set that".

# 127 = command not found: is the binary there, and is PATH right?
docker run -it --entrypoint sh myapp:1.0
> which uvicorn
> ls -la /app
> echo "$PATH"

# 137 = killed, almost always the memory limit
docker inspect NAME --format '{{.State.ExitCode}} {{.State.OOMKilled}}'

# "but I set that environment variable"
docker inspect NAME --format '{{range .Config.Env}}{{println .}}{{end}}'

Keeping your machine clean: prune and reclaim

Docker accumulates. Images you pulled once, containers you forgot to remove, build cache, and volumes from projects you stopped last spring, and then one day a build fails with no space left on device.

docker system df                 # what is using space, by category
docker system df -v              # per-image, per-container, per-volume detail

docker ps -a                     # stopped containers still hold their writable layer
docker container prune           # remove all stopped containers
docker image prune               # remove dangling (untagged) images
docker builder prune             # remove build cache
docker system prune              # containers, networks, dangling images, build cache

Start with docker system df. It tells you which category is large, so you can stop guessing. Usually it is either the build cache or images.

Worth understanding: a dangling image is one with no tag, usually because you rebuilt the same tag and the old image lost its name. Those are safe to remove. docker image prune -a is more aggressive. It removes every image not used by a container, which means re-pulling next time.

Putting it all together

Everything above, in one project. Nothing here is new. Read it as a whole and you should recognise every line and be able to say why it is there.

.git
.gitignore
.github
node_modules
__pycache__
*.pyc
.venv
.env
.env.*
dist
build
*.log
.pytest_cache
.DS_Store

# Pinned and slim: reproducible, and a fraction of the full image's size
FROM python:3.11-slim

# Unbuffered stdout, so `docker logs` shows lines as they happen
ENV PYTHONUNBUFFERED=1 \
    LOG_LEVEL=info

# A real non-root user with a fixed numeric id
RUN useradd --create-home --uid 10001 appuser

WORKDIR /app

# Dependencies first — this layer stays cached while you edit source
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Source last, owned by the app's user
COPY --chown=appuser:appuser . .

# Drop privileges after everything that needed them
USER 10001

# Documentation only; `-p` or Compose `ports:` is what publishes
EXPOSE 8000

# Exec form, so the app is PID 1 and receives SIGTERM.
# 0.0.0.0, so the published port actually reaches it.
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

services:
  api:
    build: .
    ports: ['8000:8000']
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/app
      LOG_LEVEL: debug              # override of the image's baked default
    depends_on: [db]                # startup order (readiness comes at Mid level)
    restart: unless-stopped

  db:
    image: postgres:16              # pinned major version
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes: ['pgdata:/var/lib/postgresql/data']   # named volume: state survives
    restart: unless-stopped

volumes:
  pgdata:

docker compose up -d --build      # build the image and start both services
docker compose logs -f api        # watch it come up
docker compose exec api sh        # get inside when something looks wrong
docker compose down               # stop everything; the database volume survives

Ten decisions in there are the whole lesson of this page, and each maps to a section above:

What you can now do, and what comes next

You can explain what a container is and is not, build an image from a Dockerfile, order it so rebuilds are fast, publish ports correctly, configure one image for several environments, keep data in volumes, connect containers by name, run as a non-root user, start a multi-service stack with Compose, debug a container that refuses to start, and keep your disk under control. That is a working practitioner's toolkit, enough to containerise real projects and own the Dockerfiles in a repository.

Mid-level takes every one of those topics further: the layer cache's exact rules and how to make it work in CI, multi-stage builds that cut image size by an order of magnitude, network drivers and DNS in depth, volume backup and permission handling, Compose with health checks and per-environment override files, signals and graceful shutdown, registries and immutable tags, and debugging with docker diff, docker events, and a network sidecar.

Senior then covers what you own when containers are your responsibility: what namespaces, cgroups, and capabilities give you, hardening an image so an escape is bounded, keeping secrets out of layers with BuildKit mounts, supply-chain controls including SBOMs, scanning, signing, and provenance, multi-architecture builds, resource limits and the OOM killer, GPU and machine-learning images, where Docker stops and an orchestrator begins, and debugging production while it is on fire.

Part one of three. A twenty-five-minute review of the Beginner Detailed track, then the questions interviewers ask. Mid-level reviews this plus its own material; Senior reviews all three.

The thirty-second answer

Docker packages an application with its runtime, libraries, and system dependencies into an immutable image. A container is a running instance of that image: a process on the host, isolated by kernel namespaces and cgroups rather than a hypervisor. Because the image carries its own environment, the artifact that passed CI is the artifact that runs in production.

Then the line that shows you have used it: "a container lives as long as its main process, and anything not in a volume disappears when the container is removed."

The model

Container versus VM

The follow-up: "so is a container less secure?" Yes. Shared-kernel isolation is weaker than a hypervisor, and a kernel vulnerability is an escape path. Drop privileges, and keep untrusted code out of a plain container.

One more fact: containers are a Linux kernel feature, so Docker Desktop runs a small Linux VM on macOS and Windows. Bind-mount file I/O is slower there.

Image versus container

Three containers from one image share its read-only layers on disk, and anything you write outside a volume dies with docker rm.

The commands to have ready

docker run -d -p 8080:80 --name web nginx   # detached, port-mapped, named
docker ps -a                                 # all containers; exit codes live here
docker logs -f --tail 50 web                 # follow output
docker exec -it web sh                       # shell inside a RUNNING container
docker run -it --entrypoint sh myapp         # shell in an image that crashes on start
docker build -t myapp:1.0 .                  # build; "." is the build context
docker inspect web                           # resolved config after all overrides
docker stats                                 # live CPU / memory
docker system df                             # disk usage by category
docker system prune                          # reclaim space

Lifecycle and exit codes

A container lives as long as its main process. That is why docker run ubuntu exits at once: its default command is a shell, and a shell with no terminal has nothing to read.

Dockerfile instructions

FROM python:3.11-slim
ENV PYTHONUNBUFFERED=1
RUN useradd --create-home --uid 10001 appuser
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY --chown=appuser:appuser . .
USER 10001
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Three exam favourites: RUN is build time, CMD is run time, EXPOSE publishes nothing, and ENV PYTHONUNBUFFERED=1 is why docker logs shows Python output without a buffer delay.

Layer caching and COPY order

Docker reuses a layer when its inputs are unchanged, and once a layer is invalidated every layer after it is rebuilt too. Two corollaries to state unprompted:

Layers are additive, so deleting does not shrink or hide. COPY .env . then RUN rm .env leaves the file in the earlier layer, readable by anyone who can pull the image.

Clean up inside the same RUN. Splitting apt-get update and install into separate instructions caches a stale package index and ships the package lists.

RUN apt-get update \
 && apt-get install -y --no-install-recommends curl \
 && rm -rf /var/lib/apt/lists/*

Build context and .dockerignore

The trailing . in docker build -t myapp . names the build context: the CLI uploads that whole directory to the daemon before the build starts. Without a .dockerignore you ship .git, node_modules, your virtualenv, and possibly .env: slow builds and leaked secrets.

.git
node_modules
__pycache__
*.pyc
.venv
.env
.env.*
dist
build
*.log

docker run --rm myapp ls -la /app settles "is my file missing?" and "did I ship .env?" in one command.

Ports

The mapping is host first, and inside a container your app must bind 0.0.0.0, not 127.0.0.1, or the published port looks dead. Loopback there means "reachable only from inside this container".

Configuration and secrets

Precedence, most specific wins: -e beats --env-file beats ENV. Neither ARG nor ENV is a secret. Both are image metadata, readable by anyone who can pull. At this level: secrets arrive at run time.

Volumes

docker run -v pgdata:/var/lib/postgresql/data postgres:16   # named volume
docker run -v "$(pwd)":/app myapp:dev                        # bind mount
docker run -v ./conf.yaml:/etc/app/conf.yaml:ro myapp        # read-only config

Data you write outside a volume lands in the container's writable layer and dies with docker rm.

Networking and Compose

Containers on a user-defined network reach each other by container or service name. The default bridge has no name resolution. That difference answers most "container cannot reach container" questions.

docker network create appnet
docker run -d --name db --network appnet postgres:16
docker run -d --name api --network appnet -p 8000:8000 myapp   # connects to db:5432

services:
  api:
    build: .
    ports: ['8000:8000']
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/app
    depends_on: [db]
    restart: unless-stopped
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes: ['pgdata:/var/lib/postgresql/data']
volumes:
  pgdata:

docker compose up -d
docker compose logs -f api
docker compose down          # add -v to delete volumes too

Compose creates a network and puts every service on it, addressable by service name. That is why the connection string says db.

Non-root, in two lines

RUN useradd --create-home --uid 10001 appuser
COPY --chown=appuser:appuser . .
USER 10001

USER comes after the installs, because installing to system paths needs the privilege you are about to drop. Use a numeric uid. Say the reason out loud: root in a container is root on the host kernel, with no hypervisor between them.

Debugging order

1. Logsdocker logs NAME. An exited container keeps its output until you remove it.
2. Exit codedocker ps -a. 137 is a kill (usually OOM), 127 command-not-found, 126 not-executable, and 143 a clean SIGTERM.
3. Shell without the appdocker run -it --entrypoint sh myapp, then run the command by hand.
4. Is the file there?pwd, ls -la inside. A wrong WORKDIR or a .dockerignore exclusion explains most "not found" errors.
5. Resolved configdocker inspect NAME for the real entrypoint, env, mounts, and networks after every override.

The traps, and why they share one cause

Three ideas explain most beginner failures: a container is one process, the writable layer is temporary, and build time is not run time.

Common interview questions

1. What is Docker, and why use it?It packages an app with its dependencies into an immutable image, so the artifact that passed CI is the artifact that runs in production. It removes environment drift, makes onboarding one command, and gives you fast, disposable, isolated environments.
2. Container versus virtual machine, and is a container less secure?A container shares the host kernel and is a process with a restricted view: milliseconds to start, tens of megabytes. A VM ships a full guest OS behind a hypervisor: slower, larger, stronger isolation. Yes, weaker: a kernel vulnerability is an escape path, so run non-root and keep untrusted code out of a plain container.
3. Image versus container?An image is a read-only template of stacked layers; a container is a running instance with a thin writable layer on top. One image, many containers.
4. Why does docker run ubuntu exit immediately?A container lives as long as its main process. The default command is a shell with no terminal attached, so it finishes at once. -it gives it a terminal to wait on.
5. RUN versus CMD?RUN executes at build time and its result becomes a layer. CMD is the default command when a container starts. Putting the app's start command in RUN makes the build hang forever.
6. CMD versus ENTRYPOINT?ENTRYPOINT is the fixed executable; CMD supplies default arguments. Arguments after docker run image replace CMD but are appended to ENTRYPOINT. Use ENTRYPOINT when the container should always run one program, and always use the exec form, so your process is PID 1 and receives SIGTERM.
7. Does EXPOSE publish a port?No. It is documentation for humans and tooling. -p host:container is what publishes.
8. My port mapping does not work. Why?Usually the app inside listens on 127.0.0.1, reachable only inside the container, so bind 0.0.0.0. Otherwise the -p order is reversed, or the app uses a different port than the one you mapped.
9. How do you persist data?A named volume. Anything you write to the container's writable layer is deleted with the container.
10. Named volume versus bind mount?A named volume is Docker-managed, portable, and gets correct ownership: right for databases. A bind mount maps a host directory, depends on that path, and keeps host permissions: right for development live-reload, wrong for production data.
11. How do two containers talk to each other?Put them on the same user-defined network and address each other by container or service name. The default bridge has no DNS, so this fails if you skip creating a network. Compose creates one for you, hence db:5432 in the connection string.
12. Why is my rebuild so slow?COPY order, most of the time. Copy the dependency manifest and install first, then copy the source, so source edits reuse the cached install layer. Once a layer is invalidated, everything after it rebuilds.
13. I deleted a secret in a later layer. Is it safe?No. Layers are additive, so the file is still in the earlier layer and readable by anyone who can pull the image. Rebuild without it and rotate the credential.
14. What is the build context, and why does it matter?The directory you pass to docker build, uploaded in full to the daemon. Without a .dockerignore you ship .git, node_modules, and possibly .env: a speed problem and a secret-leak path.
15. How do you pass configuration?At run time with -e or --env-file, so you promote one image across environments. Never secrets via ARG or ENV, because both land in image metadata and docker history.
16. How do you debug a container that will not start?docker logs first, then the exit code from docker ps -a, then docker run -it --entrypoint sh to get inside without running the app, then docker inspect for the resolved configuration.
17. What does exit code 137 mean?The kernel SIGKILLed the process, in most cases at the memory limit. Confirm with docker inspect --format '{{.State.OOMKilled}}'.
18. Where should an app write its logs?stdout and stderr. That is what docker logs, log shippers, and orchestrators read. A file inside the container hides them and fills the writable layer.
19. Why not run as root, and how do you avoid it?Root in the container is root on the host kernel, with no hypervisor between them, so an escape lands as root. Add a user with a fixed numeric uid, COPY --chown, and USER 10001 after the installs.
20. Why not use :latest?It is the tag Docker assumes when you give none, pointing at whatever was pushed last. It can move between two builds an hour apart, so "what is running?" becomes unanswerable and rollback undefined.

Sixty-second self-test

• Give the container-versus-VM answer in two sentences, including the security follow-up.
• Explain image versus container with an analogy.
• Say when RUN runs and when CMD runs.
• Explain what EXPOSE does and does not do.
• Give the two causes of a dead published port.
• Say why COPY order changes build speed, and what "additive layers" means.
• Name the storage that survives docker rm.
• Explain how Compose services find each other, and what depends_on does not do.
• Say what exit codes 137, 127, and 143 mean.
• Give the two lines that make a container run as non-root, and why they go last.

Part one of three. Three mistakes produce most of the errors below: you forget a container is one process, you forget the writable layer is temporary, or you confuse build time with run time. Start with the table, then the habits and practice cards.

Common errors at this level

The habits that pay off most

Practice cards

Short, self-contained exercises. Each one takes a few minutes and ends in a result you can check on screen.

1. Prove a container is just a processRun docker run --rm -it alpine sh. Inside: ps aux, hostname, uname -r. On your host, find that shell in ps aux and compare uname -r. Same kernel, two views.
2. Kill your own data on purposeRun Postgres with no volume, create a table, docker rm -f it, start it again. Then repeat with -v pgdata:/var/lib/postgresql/data. The first round loses the table, the second keeps it.
3. Break the port mappingStart your app bound to 127.0.0.1 with -p 8000:8000. Watch it refuse connections, then confirm the cause from inside with ss -tlnp. Fix it with 0.0.0.0.
4. Time both COPY ordersBuild, edit one character of source, rebuild, and note the time. Move COPY. . above the install and repeat. Watch where CACHED stops in the build output.
5. Find a "deleted" secretRUN echo "SECRET=abc" > /tmp/k then RUN rm /tmp/k. Rebuild, then docker history --no-trunc img | grep SECRET. The string is still in the layer that wrote it.
6. Cause three exit codesProduce a 127 (a CMD binary that does not exist), a 1 (an exception on startup), and a 137 (-m 16m). Diagnose each using the debugging order rather than memory.
7. Prove DNS needs your own networkStart two containers with no network flag and try ping other. Then create a network, restart both on it, and try again.
8. Drop root and check itRun docker run --rm img id before and after adding USER 10001. Then try touch /etc/test inside and read the refusal.

Debugging a container that will not start

1. Read the logsdocker logs NAME. Even a container that exited keeps its output until you remove it, so this works after a crash. You can read most failures straight out of that output.
2. Check the exit codedocker ps -a shows it. 0 = finished normally · 1 = application error · 125 = bad docker run flags · 126 = command not executable · 127 = command not found · 137 = killed, usually out of memory · 143 = stopped by SIGTERM.
3. Override the entrypoint to get a shelldocker run -it --entrypoint sh myapp starts the image without running your app, so you can look around and try the command by hand.
4. Check the file is where you thinkInside that shell: pwd, ls -la, cat the config. Most "not found" errors come from a wrong WORKDIR or a file your .dockerignore excluded.
5. Run the command manuallyType the exact CMD yourself. The interactive error message carries more detail than the one in the logs.
6. Inspect the resolved configdocker inspect NAME shows the real entrypoint, command, env, mounts, and networks, after every layer of defaults and overrides. This settles "but I set that".

# 127 = command not found: check the binary exists and PATH is right
docker run -it --entrypoint sh myapp
> which uvicorn
> ls -la /app
> echo "$PATH"

# 137 = OOM-killed: give it more memory or find the leak
docker inspect NAME --format '{{.State.ExitCode}} {{.State.OOMKilled}}'

Build-time versus run-time

Two things go wrong here: you put configuration in the image, or you expect a run-time flag to have changed the build.

Making builds fast

FROM python:3.11-slim

WORKDIR /app

# 1. Dependency manifest only: this layer is cached until it changes
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 2. Source last: edits only invalidate from here down
COPY . .

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

# Wrong: the stale index gets cached, and the lists stay in the image
RUN apt-get update
RUN apt-get install -y curl

# Right: one layer, cleaned up in the same layer
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl \
 && rm -rf /var/lib/apt/lists/*

Choosing a base image

Always pin a tag. FROM python:3.11-slim is fine; FROM python:latest means your build changes under you without a single commit.

Develop inside the container

You do not need to rebuild the image after every code change. Bind-mount your source and let the app reload itself.

services:
  api:
    build: .
    volumes:
      - .:/app                    # your source, live
      - /app/node_modules         # anonymous volume shields the image's deps
    environment:
      LOG_LEVEL: debug
    command: ['npm', 'run', 'dev']

docker compose up          # base + override, applied automatically

The second volume line is the one to get right. Mounting .:/app hides everything the image installed at /app, including node_modules. Adding an anonymous volume at /app/node_modules lets the image's installed dependencies show through the mount.

Inspect anything with --format

docker inspect returns a wall of JSON. A Go template turns it into the one answer you wanted. Keep these in your shell history.

# Why did it stop?
docker inspect api --format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}'

# Which image is this container running?
docker inspect api --format '{{.Config.Image}} → {{.Image}}'

# What environment did it get?
docker inspect api --format '{{range .Config.Env}}{{println .}}{{end}}'

# What is mounted where?
docker inspect api --format '{{range .Mounts}}{{.Type}} {{.Source}} → {{.Destination}}{{println}}{{end}}'

# Which networks and IPs?
docker inspect api --format '{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{$v.IPAddress}}{{println}}{{end}}'

# Health check history
docker inspect api --format '{{json .State.Health}}'

Useful listing variants too:

docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
docker images --format 'table {{.Repository}}:{{.Tag}}\t{{.Size}}' | sort -k2 -h

Platform gotchas

Docker behaves differently depending on where you run it. Check your row below before you assume the problem is in your code.

Keeping your machine clean

docker system df                 # what is using space, by category
docker system df -v              # per-image, per-container, per-volume detail
docker ps -a                     # stopped containers still hold their layer
docker container prune           # remove all stopped containers
docker image prune               # dangling (untagged) images
docker builder prune             # build cache
docker system prune              # containers, networks, dangling images, cache
docker system prune -a --volumes # everything unused: read this twice first

Start with docker system df so you know which category is large. Most of the time it is the build cache or images, not containers.

Small things to do from day one

Name your containers. --name web beats hunting for nostalgic_bardeen in docker ps.

Pin base image tags. Never :latest in a FROM, and never :latest in a deployment.

Set ENV PYTHONUNBUFFERED=1 (or your language's equivalent) so docker logs shows output as it happens rather than in buffered bursts.

Use --restart unless-stopped for anything you want to survive a reboot.

Set -m and --cpus locally. A runaway container should hit a limit, not freeze your laptop.

Add LABEL org.opencontainers.image.source so anyone holding the image can find the repository that produced it.

docker run -d \
  --name myapp \
  -p 8000:8000 \
  -e LOG_LEVEL=info \
  -m 512m --cpus 1 \
  --restart unless-stopped \
  myapp:1.0

The equivalent, but readable and reviewable:

services:
  app:
    build: .
    ports: ['8000:8000']
    environment:
      LOG_LEVEL: info
    mem_limit: 512m
    cpus: 1
    restart: unless-stopped

A starter setup to copy

Copy this into a new project and delete what you do not need. Every line here comes from somewhere on this page.

.git
.gitignore
.github
node_modules
__pycache__
*.pyc
.venv
.env
.env.*
dist
build
*.log
.pytest_cache
.DS_Store

FROM python:3.11-slim                       # pinned, slim, not :latest

ENV PYTHONUNBUFFERED=1 \
    LOG_LEVEL=info                          # unbuffered logs; both overridable with -e

LABEL org.opencontainers.image.source="https://github.com/my-org/myapp"

RUN useradd --create-home --uid 10001 appuser
WORKDIR /app

COPY requirements.txt .                     # manifest first: cached install
RUN pip install --no-cache-dir -r requirements.txt

COPY --chown=appuser:appuser . .            # source last

USER 10001                                  # non-root
EXPOSE 8000                                 # documentation only
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

services:
  api:
    build: .
    ports: ['8000:8000']
    env_file: [.env]
    depends_on:
      db: { condition: service_healthy }    # readiness, not just started
    mem_limit: 512m
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes: ['pgdata:/var/lib/postgresql/data']   # named volume for state
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      retries: 5
      start_period: 30s

volumes:
  pgdata:

docker compose up -d --build
docker compose logs -f api
docker compose exec api sh
docker compose down            # add -v only if you mean to delete the database

Eight details in that setup carry the lesson of this page: a .dockerignore written before the first build, unbuffered logging, the dependency manifest copied before the source, a pinned slim base, a non-root numeric user, an exec-form CMD binding 0.0.0.0, a named volume for anything that must survive, and a health check so the API waits for a database that accepts connections.

Mid-level tips take each of these further: cache keys and why CI never hits the cache, shrinking an image in order of leverage, Compose override traps, entrypoint scripts that behave, volume backup, registry hygiene, and diagnosing "works locally, not in staging".

This is part two of three. It picks up where Beginner ended and takes every topic from there further, then adds the machinery you have not met yet. Where you already know the basics, we go straight to the depth.

Where this picks up

Each section starts with the problem it solves, and ends with a Try it you can do on a real project in a few minutes.

Layers and the build cache, precisely

Beginner gave you the rule of thumb: dependencies before source. The mechanism underneath it lets you predict every cache miss instead of discovering them one rebuild at a time.

Every instruction produces a layer, a filesystem diff, and Docker decides whether to reuse it by comparing a cache key. The contents of that key differ by instruction:

Two consequences fall straight out of that table.

RUN is cached on the text of the command, not on the world it runs in. RUN apt-get update produces a layer keyed on those three words, so Docker reuses a six-week-old package index. Cache correctness, not tidiness, is why update and install must live in the same instruction.

COPY is cached on content, so touching a file does not bust it. Changing one byte in any copied file does. COPY . . hashes your whole source tree, so a .dockerignore that excludes .git and log files removes a class of spurious rebuilds.

The rule that ties the two together: once one layer's key changes, every layer after it is rebuilt, whether or not its own inputs changed. The cache is a prefix match, not a per-line lookup.

FROM node:20-slim
WORKDIR /app

COPY package*.json ./          # key = hash of those two files → rarely changes
RUN npm ci                     # ← expensive, and now nearly always CACHED

COPY . .                       # key = hash of everything else → changes constantly
RUN npm run build              # cheap by comparison

The second consequence of layering costs more when you miss it:

# The token is in this image permanently, despite the rm
RUN curl -H "Authorization: $TOKEN" -o deps.tar https://internal/deps.tar
RUN rm deps.tar

The forensic tools for all of this:

docker history myapp:1.0                                  # layers, sizes, instructions
docker history --no-trunc myapp:1.0 | grep -iE 'token|secret|password'
docker image inspect myapp:1.0 --format '{{.Size}}'
docker build --progress=plain --no-cache -t myapp:1.0 .   # see every step, cache disabled

Multi-stage builds

The problem: building needs compilers, headers, and development dependencies. Running needs none of them. A single-stage image ships the entire toolchain to production, often several hundred megabytes of software whose only purpose was to produce one directory.

A multi-stage build puts the build in one stage and the runtime in another, and copies only the result across.

# ---- stage 1: build ----
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci                       # includes devDependencies
COPY . .
RUN npm run build                # produces /app/dist

# ---- stage 2: runtime ----
FROM node:20-slim
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev            # production dependencies only
COPY --from=builder /app/dist ./dist
USER node
CMD ["node", "dist/server.js"]

Only what you COPY --from crosses the boundary. The compilers, the source tree, the dev dependencies, the .git history, and any credential used during the build stay in the discarded stage. They never exist in the shipped image, so nobody can extract them from it.

The Python equivalent uses a virtualenv as the transportable artifact, because it is a single self-contained directory:

FROM python:3.11 AS builder
WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM python:3.11-slim
RUN useradd --create-home --uid 10001 appuser
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app
COPY --chown=appuser:appuser . .
USER 10001
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Three further capabilities make stages more than a size trick:

Stop at any stage. docker build --target builder -t myapp:build . builds only up to that stage, which helps when debugging and when you want a development image that keeps the toolchain.

Run tests as a stage. A test stage that runs the suite means a failing test fails the image build, so a broken image cannot be produced at all.

FROM builder AS test
RUN npm run lint && npm test

FROM node:20-slim AS runtime
COPY --from=builder /app/dist ./dist

Copy from an image you did not build. COPY --from= accepts an image reference as well as a stage name, which is the tidy way to pull in a single binary:

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

Making images small, in order of leverage

Image size is pull time on every deploy, cache pressure in CI, storage cost in your registry, and attack surface in production. Most size "optimisation" is guesswork applied to the wrong layer, so measure first.

docker history myapp:1.0 --no-trunc --format '{{.Size}}\t{{.CreatedBy}}' | head -20
docker image inspect myapp:1.0 --format '{{.Size}}'
docker images myapp                                   # compare tags side by side

Then work down this list, ordered by how much each change typically returns:

1. Split build and runtimeA multi-stage build removes compilers, headers, dev dependencies, and the source tree in one change. Usually returns more than everything below it combined.
2. Drop to a -slim baseHundreds of megabytes, and usually a drop-in change. Do this before considering anything more exotic.
3. Clean package manager state in the same layer--no-install-recommends, then rm -rf /var/lib/apt/lists/* inside the same RUN. Cleaning in a later instruction removes nothing at all.
4. Stop shipping cachespip --no-cache-dir, npm ci --omit=dev, go build into a minimal stage. Package manager caches are dead weight in a shipped image.
5. Write a real .dockerignoreSmaller context, faster uploads, and fewer spurious cache invalidations from files that have nothing to do with the build.
6. Only then consider distroless or AlpineThe smallest runtime images, at the cost of no shell to debug in and, for Alpine, musl incompatibilities.

Distroless deserves a note because you have probably not met it. A distroless image contains your runtime and nothing else: no shell, no package manager, no ls. That removes most of the tooling an attacker would use after a compromise, and it also means you cannot docker exec into it. Weigh that operational cost before you choose it.

FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --target=/deps -r requirements.txt

FROM gcr.io/distroless/python3-debian12
WORKDIR /app
COPY --from=builder /deps /deps
COPY src/ ./src/
ENV PYTHONPATH=/deps
CMD ["-m", "src.serve"]

BuildKit and cache mounts

BuildKit is the modern build engine and the default in current Docker versions. Two of its features change how you write a Dockerfile.

Cache mounts persist a directory across builds without ever putting it in the image. That differs from layer caching: the mount survives even when the layer above it was invalidated, so a changed lockfile no longer means re-downloading every package.

# syntax=docker/dockerfile:1
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .

RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

Note there is no --no-cache-dir here. You want the cache: the mount keeps it out of the image while letting the next build reuse it. The same pattern applies to every package manager:

# apt
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && apt-get install -y --no-install-recommends curl

# npm
RUN --mount=type=cache,target=/root/.npm npm ci

# Go modules and build cache
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go build -o /out/app ./cmd/app

Bind mounts at build time let a step read a file without copying it into a layer:

RUN --mount=type=bind,source=requirements.txt,target=/tmp/requirements.txt \
    pip install -r /tmp/requirements.txt

The # syntax=docker/dockerfile:1 line at the top enables this syntax. It is a directive, must be the first line, and pins the Dockerfile frontend rather than the base image.

Configuration without rebuilding

Beginner established the principle: build once, configure at run time. Holding that line takes four mechanisms and a clear head about the precedence between them, because the pressure to bake something in arrives quickly.

The four mechanisms:

ARG PYTHON_VERSION=3.11        # usable in FROM, before the first stage
FROM python:${PYTHON_VERSION}-slim

ARG BUILD_REV=unknown          # must be re-declared inside a stage to be usable
ENV APP_REV=${BUILD_REV} \
    LOG_LEVEL=info \
    PYTHONUNBUFFERED=1

docker build --build-arg PYTHON_VERSION=3.12 --build-arg BUILD_REV="$(git rev-parse --short HEAD)" -t myapp:1.0 .

docker run -e LOG_LEVEL=debug -e DATABASE_URL="$DB_URL" myapp:1.0
docker run --env-file ./prod.env myapp:1.0
docker run --rm myapp:1.0 env                # what the container received

Two ARG details cost people time. An ARG declared before the first FROM is visible only to FROM lines, so to use it inside a stage you must declare it again there. An ARG used in a RUN becomes part of that layer's cache key, so changing it invalidates everything after it. Sometimes that is what you want, often it is a surprise.

Precedence, most specific wins:

For anything larger or more sensitive than a string, mount a file instead:

docker run -d \
  -v ./config/production.yaml:/etc/app/config.yaml:ro \
  -e CONFIG_PATH=/etc/app/config.yaml \
  myapp:1.0

That pattern, a read-only mount plus an environment variable naming the path, is how real services take structured configuration, and it keeps the image identical across environments.

Networking in depth

Beginner's rule was "create a network, address containers by name". The model underneath it is what you need as soon as something does not resolve.

The distinction that matters day to day is the first two rows: the default bridge has no name resolution, a network you create does. Docker runs an embedded DNS server at 127.0.0.11 inside containers on user-defined networks, resolving container names, network aliases, and Compose service names.

docker network create appnet
docker network ls
docker network inspect appnet                 # subnet, gateway, connected containers

docker run -d --name db  --network appnet postgres:16
docker run -d --name api --network appnet -p 8000:8000 myapi:1.0
# api connects to postgres://db:5432, and "db" resolves through Docker's DNS

docker network connect othernet api           # a container can be on several networks
docker network disconnect othernet api

Three capabilities beyond the basics:

Aliases give a container additional names on a network, which is how you swap an implementation without touching connection strings:

docker run -d --name postgres-16 --network appnet --network-alias db postgres:16
# clients keep connecting to "db"; you decide which container answers

host networking removes the network namespace entirely: no port mapping, no isolation, and the container's ports are the host's ports. It is occasionally right for performance-sensitive or network-inspecting workloads. It is also Linux-only, and on Docker Desktop it does not behave the way you expect.

Reaching the host from inside a container is a common need and has a platform-specific answer:

# Docker Desktop (macOS, Windows): built in
docker run --rm curlimages/curl curl -s http://host.docker.internal:5432

# Plain Linux: you have to add the mapping yourself
docker run --rm --add-host=host.docker.internal:host-gateway curlimages/curl \
  curl -s http://host.docker.internal:5432

Debug without installing tools into your image: attach a container that already has them to the target's network namespace.

docker run --rm -it --network container:api nicolaka/netshoot
> dig db                      # does the name resolve, and to what?
> curl -v http://db:5432      # is anything listening?
> ss -tlnp                    # what is bound, on which interface?
> traceroute db

Volumes in depth

Beginner covered named volumes versus bind mounts. There are five mount types in total, and the two you have not met solve real problems.

The long --mount form is more verbose and clearer, and it is what you want in anything shared:

docker run -d \
  --mount type=volume,source=pgdata,target=/var/lib/postgresql/data \
  --mount type=bind,source="$(pwd)/config",target=/etc/app,readonly \
  --mount type=tmpfs,target=/tmp,tmpfs-size=64m \
  postgres:16

Anonymous volumes appear whether you ask for them or not: an image with a VOLUME instruction creates one on every docker run, and each run leaves another behind. They have one useful application, shielding a subdirectory from a bind mount:

services:
  api:
    volumes:
      - .:/app                    # your source, live
      - /app/node_modules         # anonymous volume keeps the image's deps visible

Without that second line, mounting your project over /app hides everything the build installed there, including node_modules. The anonymous volume masks that one subdirectory back.

tmpfs puts a path in memory. Use it when a container needs scratch space that you do not want on disk, typically a read-only container that still needs somewhere to write.

Backup and restore comes up more often than people expect, and the pattern is always the same: a throwaway container with the volume attached and a bind mount to write to.

# Back up a named volume to a tarball on the host
docker run --rm \
  -v pgdata:/data:ro \
  -v "$(pwd)":/backup \
  alpine tar czf /backup/pgdata-$(date +%F).tar.gz -C /data .

# Restore into a fresh volume
docker volume create pgdata-restored
docker run --rm -v pgdata-restored:/data -v "$(pwd)":/backup \
  alpine tar xzf /backup/pgdata-2024-05-01.tar.gz -C /data

# Copy one volume to another
docker run --rm -v pgdata:/from:ro -v pgdata-copy:/to alpine sh -c 'cp -a /from/. /to/'

# How big is it, and what is inside?
docker run --rm -v pgdata:/data:ro alpine du -sh /data
docker system df -v

Health checks

A running container is not necessarily a working one. A process can be alive while its dependency is unreachable, its thread pool is deadlocked, or it never finished starting. A health check is how Docker, Compose, and every orchestrator tell the difference.

HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD curl -fsS http://localhost:8000/health || exit 1

The check is a command run inside the container, and its exit code is the whole result: 0 is healthy, 1 is unhealthy. That is why curl -f matters. Without -f, curl exits 0 even on an HTTP 500.

docker ps                                                    # STATUS shows (healthy)
docker inspect --format '{{json .State.Health}}' api         # full history of checks
docker inspect --format '{{.State.Health.Status}}' api       # the current state only
docker events --filter event=health_status                   # watch transitions live

--start-period is the option people miss, and its absence produces a container that restarts forever: a service that takes forty seconds to warm up fails its first three checks, gets marked unhealthy, and is restarted before it ever finishes starting.

A slim or distroless image often has no curl. Use the runtime you already have:

# Python, no extra packages needed
HEALTHCHECK --interval=30s --start-period=40s --retries=3 \
  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/health').status==200 else 1)"

# Node
HEALTHCHECK CMD node -e "require('http').get('http://localhost:3000/health',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"

Signals, PID 1, and graceful shutdown

Beginner told you to use the exec form of CMD. Signal delivery is the reason, and dropped requests on every deploy are the cost of getting it wrong.

When you run docker stop, Docker sends SIGTERM to process 1 inside the container, waits ten seconds by default, then sends SIGKILL. Whether your application hears that signal depends on what PID 1 is.

# Exec form: your process IS PID 1 and receives signals
CMD ["node", "server.js"]

# Shell form: PID 1 is /bin/sh, which does NOT forward signals to your app
CMD node server.js

The symptom is unmistakable once you know it: docker stop takes ten seconds and then the container dies hard. That is the grace period expiring because nothing responded, not slowness.

docker stop api                          # default 10s grace
docker stop -t 30 api                    # allow 30s to drain
docker inspect api --format '{{.State.ExitCode}}'   # 143 = clean SIGTERM, 137 = SIGKILL

Most real images need something to happen before the app starts: wait for a dependency, run a migration, resolve configuration. Done carelessly, that entrypoint script becomes the reason your container ignores docker stop.

#!/bin/sh
set -eu

# Wait for a dependency, but bounded. Never loop forever.
tries=0
until nc -z "${DB_HOST:-db}" "${DB_PORT:-5432}"; do
  tries=$((tries + 1))
  [ "$tries" -ge 30 ] && { echo "db unreachable after 30 tries" >&2; exit 1; }
  echo "waiting for db ($tries)"
  sleep 1
done

[ "${RUN_MIGRATIONS:-false}" = "true" ] && ./manage.py migrate --noinput

exec "$@"          # ← replaces the shell, so your app becomes PID 1

COPY --chmod=0755 docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

One more PID 1 consideration: a real init process reaps zombies. If your container spawns child processes that it does not wait on, add --init (or init: true in Compose) and Docker inserts a minimal init as PID 1.

Resource limits

Without limits, one container can consume all the memory on a host and the kernel will kill something, not necessarily the guilty process. Limits turn a runaway container into a bounded, diagnosable failure rather than an outage.

docker run -d \
  -m 512m \                       # hard memory ceiling
  --memory-reservation 256m \     # soft target under host pressure
  --cpus 1.5 \                    # CPU quota, in cores
  --pids-limit 200 \              # process count cap, the fork-bomb defence
  --restart on-failure:5 \        # bounded retries, not a forever crash loop
  myapp:1.0

docker stats --no-stream
docker inspect --format '{{.State.OOMKilled}}' myapp        # true after a 137

Exit code 137 with OOMKilled: true is the memory limit doing its job. The container asked for more than it was allowed and the kernel stopped it. Compare that with the alternative: an unlimited container takes the host's memory and the kernel kills your database instead.

The same settings in Compose, where they belong for anything a team runs:

services:
  api:
    build: .
    mem_limit: 512m
    cpus: 1.0
    pids_limit: 200
    restart: unless-stopped

Docker Compose in depth

Beginner used Compose to start an app and a database. At this level Compose describes how your whole system fits together, and it is the file a colleague reads to understand that system.

services:
  api:
    build:
      context: .
      target: runtime              # stop at a specific multi-stage target
      args:
        BUILD_REV: ${GIT_SHA:-dev}
    image: ghcr.io/org/app:${TAG:-dev}
    ports: ['8000:8000']
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/app
      REDIS_URL: redis://cache:6379
      LOG_FORMAT: json
    env_file: [.env]
    depends_on:
      db:
        condition: service_healthy     # wait for READY, not merely started
      cache:
        condition: service_started
    healthcheck:
      test: ['CMD-SHELL', 'curl -fsS http://localhost:8000/health || exit 1']
      interval: 30s
      timeout: 3s
      start_period: 40s
      retries: 3
    mem_limit: 512m
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes: ['pgdata:/var/lib/postgresql/data']
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  cache:
    image: redis:7
    command: ['redis-server', '--appendonly', 'yes']
    volumes: ['redisdata:/data']

volumes:
  pgdata:
  redisdata:

docker compose up -d --build
docker compose ps                     # includes health status
docker compose logs -f api
docker compose exec api sh
docker compose restart api            # one service
docker compose up -d --no-deps api    # rebuild and replace one service only
docker compose down                   # keeps volumes
docker compose down -v                # deletes volumes too

Layering Compose files per environment

compose.override.yaml is applied automatically on top of compose.yaml. That is convenient locally and dangerous in a pipeline.

# Local development only, applied automatically
services:
  api:
    build:
      target: builder               # keep the toolchain for debugging
    volumes:
      - .:/app                      # live reload
      - /app/node_modules           # shield the image's dependencies
    environment:
      LOG_FORMAT: pretty
      LOG_LEVEL: debug
    command: ['uvicorn', 'app:app', '--reload', '--host', '0.0.0.0']

docker compose up                                          # base + override
docker compose -f compose.yaml -f compose.prod.yaml up -d   # explicit set, no override
docker compose config                                       # print the MERGED result
docker compose -f compose.yaml config                       # what production gets

docker compose config is the debugging tool here. It prints the fully merged, variable-interpolated file, which is what runs and often not what you believe you wrote. If a colleague reports behaviour you cannot reproduce, this settles it in one command.

Profiles

Profiles let one file describe optional services, so the heavy extras only start when asked for:

services:
  api:
    build: .
  db:
    image: postgres:16
  mailhog:
    image: mailhog/mailhog
    profiles: [dev]
  loadtest:
    image: grafana/k6
    profiles: [perf]

docker compose up -d                       # api and db only
docker compose --profile dev up -d         # plus mailhog
docker compose --profile perf run loadtest run /scripts/load.js

Registries, tags, and digests

Beginner said "pin a tag, never deploy :latest". Once more than one machine is involved, the part that matters is this: a tag is a mutable pointer.

myapp:1.4.2 is a label that currently points at one image. Nothing stops someone repushing it tomorrow with different contents. Two hosts pulling the same tag an hour apart can be running different code.

The only immutable reference is the digest, a content hash of the image:

docker build -t ghcr.io/my-org/myapp:1.4.2 .
docker tag ghcr.io/my-org/myapp:1.4.2 ghcr.io/my-org/myapp:latest

echo "$TOKEN" | docker login ghcr.io -u USERNAME --password-stdin
docker push ghcr.io/my-org/myapp:1.4.2
docker push ghcr.io/my-org/myapp:latest

# The digest cannot change, by definition
docker inspect --format '{{index .RepoDigests 0}}' ghcr.io/my-org/myapp:1.4.2
docker pull ghcr.io/my-org/myapp@sha256:9b2c...

One practice follows from all of it:

# One build, several names, pushed once
docker buildx build \
  -t ghcr.io/org/app:sha-${GIT_SHA} \
  -t ghcr.io/org/app:main \
  --push .

# Promote by re-tagging the same digest, with no rebuild
DIGEST=$(docker buildx imagetools inspect ghcr.io/org/app:sha-${GIT_SHA} --format '{{.Manifest.Digest}}')
docker buildx imagetools create -t ghcr.io/org/app:production ghcr.io/org/app@${DIGEST}

Layer caching is nearly free locally and does nothing in CI by default, because every CI run starts on a clean machine with an empty layer store. You have to export the cache somewhere:

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    push: ${{ github.event_name != 'pull_request' }}
    tags: ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

mode=max exports intermediate layers as well. With mode=min only the final stage is cached, which does little for a multi-stage build: the expensive builder stage misses every time.

Debugging beyond docker logs

Beginner gave you an ordered checklist for a container that will not start. At this level the failures are subtler: it starts, it runs, and it behaves differently from how it behaves on your machine. That needs different tools.

# What has this container actually written? A = added, C = changed, D = deleted
docker diff api

# Timeline of everything Docker did to this container
docker events --since 30m --filter container=api

# Copy a file out to look at it properly
docker cp api:/app/config.resolved.json ./

# Network debugging without polluting your image
docker run --rm -it --network container:api nicolaka/netshoot
> dig db
> curl -v http://db:5432
> ss -tlnp

# Live resource usage, and the OOM verdict
docker stats --no-stream
docker inspect api --format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}'

docker diff is the underused one. It compares the container's filesystem against its image and tells you what changed, which is how you discover that your "volume" is writing into the container's writable layer because a path was misspelled.

"Works locally, not in staging"

Almost always one of five differences. Check them in this order, because they are ordered by how often they are the answer:

docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/org/app:1.4.2 --push .
docker buildx imagetools inspect ghcr.io/org/app:1.4.2      # confirm both architectures

Putting it all together

Everything from this level in one project. Nothing here is new. Read it as a whole and you should be able to justify every line.

# syntax=docker/dockerfile:1

# ---------- build stage: toolchain lives and dies here ----------
FROM python:3.11-slim AS builder

RUN apt-get update \
 && apt-get install -y --no-install-recommends build-essential \
 && rm -rf /var/lib/apt/lists/*

RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

WORKDIR /app
COPY requirements.txt .
# Cache mount: fast warm rebuilds, and nothing added to the image
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

# ---------- test stage: a red test cannot produce an image ----------
FROM builder AS test
COPY . .
RUN ruff check . && pytest -q

# ---------- runtime stage: only what is needed to serve ----------
FROM python:3.11-slim AS runtime

ARG BUILD_REV=unknown
ENV APP_REV=${BUILD_REV} \
    LOG_LEVEL=info \
    PYTHONUNBUFFERED=1 \
    PATH="/opt/venv/bin:$PATH"

RUN useradd --create-home --uid 10001 appuser

COPY --from=builder /opt/venv /opt/venv

WORKDIR /app
COPY --chown=appuser:appuser . .

USER 10001
EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/health').status==200 else 1)"

# Exec form, so the process is PID 1 and SIGTERM reaches it
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

services:
  api:
    build:
      context: .
      target: runtime
      args:
        BUILD_REV: ${GIT_SHA:-dev}
    image: ghcr.io/org/app:${TAG:-dev}     # same image, tag from the environment
    ports: ['8000:8000']
    env_file: [.env]
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/app
    depends_on:
      db:
        condition: service_healthy          # readiness, not merely started
    mem_limit: 512m
    cpus: 1.0
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes: ['pgdata:/var/lib/postgresql/data']
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      retries: 5
      start_period: 30s
    restart: unless-stopped

volumes:
  pgdata:

docker compose up -d --build
docker compose config                 # verify the merged file is what you intended
docker compose ps                     # health status included
docker stop -t 30 $(docker compose ps -q api)   # graceful, with time to drain

Nine decisions in there are the whole lesson of this level:

Where you are now

You can predict cache behaviour instead of discovering it, cut an image by an order of magnitude with staged builds and cache mounts, keep configuration and secrets out of layers, reason about networks and DNS, back up and restore volumes, run a stack that starts in dependency order and reports real health, shut down gracefully, bound resource usage, and publish images with references that mean something.

Senior takes every one of these further, with a security, scale, or ownership dimension. What isolation consists of (namespaces, cgroups, capabilities, seccomp) and therefore what an escape means. Hardening so a compromise is bounded: non-root, read-only root filesystem, dropped capabilities, no-new-privileges. Secrets that never touch a layer, via BuildKit secret mounts and SSH forwarding. Supply chain: digest-pinned bases, SBOMs, scanning that people do not learn to ignore, signing, provenance, and admission policy. Multi-architecture builds on native runners. The OOM killer, and runtimes that cannot see their own cgroup. GPU and machine-learning images, where weights do not belong in a layer. Where Docker stops and an orchestrator begins. Debugging production while it is on fire.

Part two of three. A cumulative review of Beginner and Mid-level material, organised by topic rather than level, in about thirty-five minutes. Fast review first, common questions at the end. Senior reviews all three.

Where this picks up

Foundations, in one screen

Docker packages an application with its runtime and dependencies into an immutable image. A container is a running instance: a process on the host isolated by namespaces and cgroups, not a virtual machine. The artifact that passed CI is the artifact that runs in production.

Container versus VM: shared kernel, milliseconds, tens of MB, isolated by kernel features. A VM carries a full guest OS, tens of seconds, gigabytes, isolated by a hypervisor. Container isolation is weaker; say so before they ask.

Image versus container: read-only template versus running instance with a thin writable layer. One image, many containers. Anything written outside a volume dies with docker rm.

A container lives as long as its main process. That is why docker run ubuntu exits at once.

EXPOSE publishes nothing. RUN is build time, CMD is run time. Inside a container, bind 0.0.0.0.

Commands and exit codes

docker run -d -p 8080:80 --name web nginx
docker ps -a                          # exit codes live here
docker logs -f --tail 50 web
docker exec -it web sh
docker run -it --entrypoint sh myapp  # shell in an image that crashes on start
docker inspect web                    # resolved config after all defaults
docker diff web                       # what the container has written
docker events --since 30m             # timeline of daemon activity
docker stats                          # live CPU / memory
docker history myapp:1.0              # per-layer sizes and instructions
docker system df -v && docker system prune

Dockerfile instructions

Layers and the build cache

A layer is reused when its cache key is unchanged, and once one layer is invalidated every layer after it rebuilds. Each instruction builds that key differently, and that is what an interviewer probes:

COPY package*.json ./     # key = hash of those files → changes rarely
RUN npm ci                # ← expensive, now CACHED
COPY . .                  # key = hash of everything else → changes constantly

Two consequences to state without prompting:

RUN is cached on text, not on the world. RUN apt-get update alone reuses a weeks-old package index, which is why update and install must share one instruction.

Layers are additive, so deleting does not shrink or hide. A file added then removed is still in the earlier layer, still counted in the size, still extractable.

# Right: one layer, cleaned inside that same layer
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl \
 && rm -rf /var/lib/apt/lists/*

Multi-stage builds

FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-slim
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=builder /app/dist ./dist
USER node
CMD ["node", "dist/server.js"]

Only what you COPY --from crosses the boundary. Compilers, source, dev dependencies, and any build-time credential stay in the discarded stage. --target stops at a stage, which is also how a test stage makes a failing test fail the image build. COPY --from= accepts an image reference too, not only a stage name.

BuildKit cache mounts

Separate from layer caching: a cache mount persists a directory across builds without ever entering the image.

# syntax=docker/dockerfile:1
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt
RUN --mount=type=cache,target=/root/.npm npm ci
RUN --mount=type=cache,target=/go/pkg/mod go build -o /out/app ./cmd/app

Note the absence of --no-cache-dir: you want the cache, and the mount keeps it out of the image. A warm rebuild drops from minutes to seconds even when the lockfile changed. The third mount type, type=secret, is Senior material.

Configuration and secrets

Precedence, most specific wins: -e → --env-file → ENV. Neither ARG nor ENV is a secret; both are image metadata readable by anyone who can pull. An ARG before the first FROM is visible only to FROM, so re-declare it inside a stage to use it there.

The principle behind all of it: build once, promote the same artifact. If production rebuilds, production runs something CI never tested.

Networking

docker network create appnet
docker run -d --name db  --network appnet postgres:16
docker run -d --name api --network appnet -p 8000:8000 myapi
# api connects to postgres://db:5432, resolved by Docker's embedded DNS at 127.0.0.11

Docker runs an embedded resolver inside containers on user-defined networks, resolving container names, --network-alias values, and Compose service names. Aliases let you swap an implementation without touching connection strings.

Volumes

# Back up a named volume: throwaway container, volume + bind mount, tar
docker run --rm -v pgdata:/data:ro -v "$(pwd)":/backup alpine \
  tar czf /backup/pgdata.tar.gz -C /data .

Two facts to have ready. Bind-mount permission errors come from a UID mismatch between host and container: match it with --user "$(id -u):$(id -g)", or use a named volume. a bind mount hides whatever was already at that path, which is where node_modules disappears; an anonymous volume over the subdirectory masks it back.

For anything transactional, tarring a live data directory gives a torn copy. Use the database's own tooling (pg_dump) instead.

Health checks and signals

HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD curl -fsS http://localhost:8000/health || exit 1

The check runs inside the container and its exit code is the whole result. curl -f matters: without -f, curl exits 0 on an HTTP 500. Skip --start-period and a service that takes forty seconds to warm up gets marked unhealthy and restarted before it finishes booting.

docker inspect --format '{{json .State.Health}}' api    # full check history

The symptom is hard to miss: docker stop takes ten full seconds and then the container dies hard. Entrypoint scripts must end with exec "$@" for the same reason, bound their wait loops, and keep migrations opt-in.

#!/bin/sh
set -eu
tries=0
until nc -z "${DB_HOST:-db}" "${DB_PORT:-5432}"; do
  tries=$((tries + 1))
  [ "$tries" -ge 30 ] && { echo "db unreachable" >&2; exit 1; }
  sleep 1
done
exec "$@"          # ← replaces the shell, so your app becomes PID 1

A startup wait is not a substitute for run-time retries: databases restart and networks blip long after boot.

Resource limits

docker run -d -m 512m --memory-reservation 256m --cpus 1.5 \
  --pids-limit 200 --restart on-failure:5 myapp:1.0

docker inspect --format '{{.State.OOMKilled}}' myapp     # true after a 137

Without limits, one container consumes all host memory and the OOM killer may take something else. With a limit, the kill is scoped to that cgroup and recorded.

Compose

services:
  api:
    build: { context: ., target: runtime }
    image: ghcr.io/org/app:${TAG:-dev}
    ports: ['8000:8000']
    env_file: [.env]
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/app
    depends_on:
      db: { condition: service_healthy }
    healthcheck:
      test: ['CMD-SHELL', 'curl -fsS http://localhost:8000/health || exit 1']
      interval: 30s
      start_period: 40s
    mem_limit: 512m
    restart: unless-stopped
  db:
    image: postgres:16
    environment: { POSTGRES_PASSWORD: secret }
    volumes: ['pgdata:/var/lib/postgresql/data']
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      retries: 5
      start_period: 30s
volumes:
  pgdata:

docker compose up -d --build
docker compose config           # the MERGED file: the debugging tool
docker compose --profile dev up -d
docker compose down -v          # -v also deletes volumes

Three more Compose facts to have ready. compose.override.yaml is applied without being named, which helps locally and hurts in CI, so pass -f explicitly there. Profiles keep optional services out of a default up. Compose's own .env substitutes values into the YAML, a different mechanism from env_file:, which passes variables into the container.

Registries, tags, and digests

A tag is a mutable pointer; only a digest is immutable.

docker build -t ghcr.io/org/app:sha-a1b2c3d .
echo "$TOKEN" | docker login ghcr.io -u USER --password-stdin
docker push ghcr.io/org/app:sha-a1b2c3d

docker inspect --format '{{index .RepoDigests 0}}' ghcr.io/org/app:sha-a1b2c3d
docker pull ghcr.io/org/app@sha256:9b2c...       # cannot change

# Promote by re-tagging the same digest, no rebuild
docker buildx imagetools create -t ghcr.io/org/app:production ghcr.io/org/app@sha256:9b2c...

Immutable :1.4.2 and :sha-a1b2c3d for deployments; moving :latest for humans; digests for anything sensitive. Never deploy a moving tag. Two hosts pulling it an hour apart can run different code, and rollback becomes undefined.

Layer caching does nothing in CI by default, because each run starts with an empty layer store. Export it:

- uses: docker/build-push-action@v6
  with:
    tags: ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

mode=max exports intermediate layers. mode=min caches only the final stage, which buys you little on a multi-stage build.

Debugging

docker logs --tail 100 api            # 1. output
docker ps -a                          # 2. exit code
docker inspect api                    # 3. resolved config
docker run -it --entrypoint sh myapp   # 4. shell without the app
docker diff api                       # 5. what changed on disk
docker events --since 30m --filter container=api    # 6. timeline
docker run --rm -it --network container:api nicolaka/netshoot   # 7. network tools
docker cp api:/app/config.json ./     # 8. pull a file out

docker diff is the underused one: it separates writes to the writable layer from writes to a volume, which is how you find a misspelled mount path.

"Works locally, not in staging"

Five differences, in the order they usually turn out to be the answer:

"exec format error", or unexplained slowness from silent QEMU emulation, points to the architecture. Check with docker image inspect --format '{{.Architecture}}'.

Common interview questions

1. Container versus virtual machine, and is a container less secure?Shared kernel, process-level isolation via namespaces and cgroups, milliseconds and megabytes. A VM runs a full guest OS behind a hypervisor. Yes, weaker: a kernel vulnerability is an escape path, so run non-root and keep untrusted code out of a plain container.
2. Walk me through the layer cache. What invalidates it?Each instruction has a cache key: RUN hashes the command string, COPY the file contents, FROM the base digest. Once one key changes, every layer after it rebuilds. So you install the dependency manifest before copying source, and apt-get update alone reuses a stale index.
3. What is a multi-stage build and what problem does it solve?Building needs compilers and dev dependencies; running does not. A build stage produces the artifact and the runtime stage copies only that with COPY --from. The toolchain, source, and any build credentials stay in the discarded stage: smaller image, smaller attack surface.
4. I deleted a secret in a later layer. Is it safe?No. Layers are additive: the file sits in the earlier layer, readable by anyone who can pull the image. Rebuild without it and rotate the credential, because copies are already cached where you cannot reach them.
5. How is a cache mount different from layer caching?Layer caching reuses a whole layer when its key is unchanged. A cache mount persists a directory across builds without entering the image, so a changed lockfile no longer means re-downloading every package. It survives layer invalidation, which layer caching cannot.
6. How do you pass configuration and secrets?Configuration at run time with -e or --env-file, so one image is promoted across environments. Never secrets via ARG or ENV; both land in image metadata and docker history. Use mounted files or run-time environment from a secret store.
7. Two containers cannot talk to each other. Debug it.Check they are on the same user-defined network, because the default bridge has no DNS. Check the app connects to the container name, not localhost, which inside a container means that container. Then verify inside the namespace with a netshoot sidecar: dig db, curl -v http://db:5432, ss -tlnp.
8. Named volume or bind mount?Named volume for state: Docker-managed, portable, ownership initialised correctly. Bind mount for development live-reload. In production a bind mount ties you to a host path and brings UID permission problems that Mac and Windows users never see.
9. How would you back up a named volume?A throwaway container with the volume mounted read-only plus a host bind mount, and tar. For anything transactional, use the database's own tooling: tarring a live Postgres data directory gives a torn copy.
10. My app starts before the database is ready.depends_on waits for the container to start, nothing more. Add a healthcheck to the database and condition: service_healthy to the dependant, then add connection retry to the app anyway, because readiness can be lost long after boot.
11. What does --start-period do?A grace window during boot where health check failures do not count towards --retries. Without it, a service that takes forty seconds to warm up is marked unhealthy and restarted before it comes up.
12. Why does my container ignore docker stop and take ten seconds to die?Shell-form CMD makes /bin/sh PID 1, and it does not forward SIGTERM, so Docker SIGKILLs it mid-request when the grace period ends. Use the exec form, and end entrypoint scripts with exec "$@". A clean stop exits 143; a hard kill exits 137.
13. A container exits with 137. What happened?It was SIGKILLed, in most cases by the memory limit. Confirm with docker inspect --format '{{.State.OOMKilled}}'. Then raise the limit or find the leak. A scoped kill beats an unlimited container eating the host's memory while the OOM killer picks a different victim.
14. A container is OOM-killed at 512 MB while apparently idle.The runtime read the host's memory rather than the cgroup limit and sized its heap for the whole machine. Common with older JVMs and Node. Use a container-aware runtime, or set --max-old-space-size yourself.
15. Why not deploy :latest?A tag is a mutable pointer. Two hosts pulling it an hour apart can run different code, rollback is undefined, and no one on the team can answer "what is running?". Deploy an immutable version or SHA tag, or a digest.
16. What does "build once, promote" mean and why does it matter?Build one image, tag it with the commit SHA, and promote that artifact through staging into production. If production rebuilds, the base image may have moved and a transitive dependency may have published a patch, so you ship something CI never tested.
17. How would you shrink a 1.2 GB image?docker history first to find the fat layers. Then in order of leverage: multi-stage build, a -slim base, --no-install-recommends with apt lists cleaned in the same RUN, no package caches, a real .dockerignore. Measure after each change instead of doing all of it blind.
18. Is Alpine the right choice for size?Not always. musl instead of glibc means prebuilt Python wheels and some Node native modules do not apply, so you compile from source. That needs a toolchain and often ends up larger and slower to build than -slim. Measure first.
19. Why does layer caching not help in CI?Every CI run starts on a clean machine with an empty layer store. Export the cache to a backend (type=gha, a registry, or local disk) with mode=max, so intermediate stages come along too.
20. "It works locally but not in staging." How do you approach it?Five checks in order: compare digests not tags; compare the resolved environment; look for a local compose.override.yaml mounting source over the image; check the architecture, because Apple Silicon builds arm64; confirm the file is in the image with docker run --rm img ls -la /app.
21. How do you debug a container without installing tools into the image?Attach a container that already has them to the target's network namespace: docker run --rm -it --network container:api nicolaka/netshoot. Installing curl into a production image enlarges every deployment from then on to fix a temporary problem.
22. What does docker diff tell you?Everything the container has written relative to its image. Use it to separate a write to the writable layer from a write to a volume, which is how you find a misspelled mount path.

Final self-test

• State the cache key for RUN, COPY, and FROM, and what invalidation does to later layers.
• Say why deleting a file in a later layer does not remove it, and what to do if a secret shipped.
• Explain what crosses a multi-stage boundary, and name two other uses for stages.
• Say how a cache mount differs from layer caching.
• Name the four configuration mechanisms and which are visible in the image.
• Explain why the default bridge breaks name resolution, and what localhost means inside a container.
• Describe the depends_on readiness gap and both halves of the fix.
• Explain exec form versus shell form, and give the exit code for each shutdown.
• Say what exit 137 with OOMKilled: true means, and one reason it happens at an unexpectedly low limit.
• Give the only immutable image reference, and why promotion beats rebuilding.
• Say how to make layer caching work in CI, and why mode=min is nearly useless.
• Name the five checks for "works locally, not in staging", in order.

Part two of three. At this level your images build and your stacks run, so the problems change character. They are no longer "why won't this start" but "why is this image 1.2 GB", "why does CI rebuild everything", and "why does this work locally and not in staging". Start with the error table, then the practices and practice cards underneath it.

Common errors at this level

Cumulative: Beginner's errors still apply, and these are the ones that appear once things work.

The practices that pay off most

Practice cards

1. Find your invalidation pointBuild twice with no changes and confirm every step is CACHED. Edit one character and rebuild, noting the exact instruction where CACHED stops. It is usually higher up than you assumed.
2. Halve an imageRun docker history --no-trunc and identify your three largest layers. Apply multi-stage, measure. Then drop to -slim, measure again. One change at a time.
3. Prove the cache mountAdd a pip or npm cache mount, build, change one line of the manifest, and rebuild. Compare against the same change without the mount.
4. Gate the image on testsAdd a test stage that runs your suite, break a test, and confirm no image is produced.
5. Close the readiness gapAdd health checks and condition: service_healthy, then remove them and confirm the first request after a cold up fails.
6. Time both shutdownsBuild with the shell form and run time docker stop NAME: ten seconds, exit 137. Switch to exec form and repeat: under a second, exit 143.
7. Round-trip a volumeBack up a named volume with the tar pattern, delete it, restore into a fresh volume, and start a container against the restored copy.
8. Move a tag under yourselfPush an image, record its digest, rebuild with a trivial change, repush the same tag, and confirm the digest changed while the digest reference still resolves to the original.
9. Diff the two merged ComposesRun docker compose config and docker compose -f compose.yaml config, and diff them. Everything in that diff is a local-only assumption.

Shrinking an image, in order of leverage

Measure first: docker history myapp:1.0 shows every layer with its size and the instruction that made it.

1. Split build and runtimeA multi-stage build removes compilers, headers, dev dependencies, and the source tree in one change. Usually worth more than everything below combined.
2. Drop to a -slim baseHundreds of megabytes, and almost always a drop-in change.
3. Clean package manager state in the same layer--no-install-recommends, then rm -rf /var/lib/apt/lists/* inside the same RUN. Cleaning in a later layer removes nothing.
4. Stop shipping cachespip --no-cache-dir, npm ci --omit=dev, and cache mounts instead of baked-in caches.
5. Write a real .dockerignoreSmaller context, faster uploads, and fewer spurious cache invalidations from unrelated files.
6. Only then consider distroless or AlpineSmallest runtime images, at the cost of no shell to debug in and, for Alpine, musl incompatibilities.

docker history myapp:1.0 --no-trunc --format '{{.Size}}\t{{.CreatedBy}}' | head -20
docker image inspect myapp:1.0 --format '{{.Size}}'
docker run --rm myapp:1.0 du -xh --max-depth=2 / 2>/dev/null | sort -h | tail -15

That third command is the one people do not know: it tells you where the space went inside the image, which is often a dataset or a cache you forgot about rather than the base.

Making the cache work in CI

Layer caching is nearly free locally and does nothing in CI by default, because every run starts on a clean machine with an empty layer store. You have to export it somewhere.

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    push: ${{ github.event_name != 'pull_request' }}
    tags: ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

mode=max exports intermediate layers too. With mode=min only the final stage is cached, which is nearly useless for a multi-stage build, because the expensive builder stage misses every time.

Compose in practice

docker compose config is the debugging tool. It prints the fully merged, variable-interpolated file, which is what runs, and often not what you think you wrote.

docker compose config                                   # merged result
docker compose -f compose.yaml -f compose.prod.yaml config
docker compose ps                                       # health status included
docker compose logs -f --tail 100 api
docker compose exec api sh
docker compose up -d --no-deps --build api              # replace one service only
docker compose down -v                                  # -v also deletes volumes

Two more distinctions worth internalising. Compose's own .env file substitutes values into the YAML; env_file: passes variables into the container, and mixing them up produces empty variables that look like a bug. profiles: keeps heavy optional services out of a default up, which is much better than commenting them out.

Debugging without polluting the image

The instinct is to apt-get install curl into the image so you can debug it. Resist. You are permanently enlarging every deployment to solve a temporary problem. Attach a sidecar to the container's network namespace instead.

# Full network toolkit, sharing the target container's network
docker run --rm -it --network container:api nicolaka/netshoot
> dig db                 # does the name resolve?
> curl -v http://db:5432 # is anything listening?
> ss -tlnp               # what is bound, and to which interface?
> traceroute db

docker diff is the underused one. It compares the container's filesystem against its image, which is how you discover that your "volume" is writing into the writable layer because a mount path was misspelled.

"Works locally, not in staging"

Almost always one of five differences. Check them in this order, because that is roughly how often each is the answer.

docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/org/app:1.4.2 --push .
docker buildx imagetools inspect ghcr.io/org/app:1.4.2     # confirm both arches

Entrypoint scripts that behave

Most real images need something to happen before the app starts: wait for a dependency, run a migration, resolve configuration. Done carelessly, the entrypoint script becomes the reason your container ignores docker stop.

#!/bin/sh
set -eu

# Wait for a dependency, but bounded — never loop forever
tries=0
until nc -z "${DB_HOST:-db}" "${DB_PORT:-5432}"; do
  tries=$((tries + 1))
  [ "$tries" -ge 30 ] && { echo "db unreachable after 30 tries" >&2; exit 1; }
  echo "waiting for db ($tries)"
  sleep 1
done

[ "${RUN_MIGRATIONS:-false}" = "true" ] && ./manage.py migrate --noinput

exec "$@"          # ← replaces the shell, so your app becomes PID 1

COPY --chmod=0755 docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Volume operations you will need

Backing up and moving named volumes comes up far more often than people expect, and the pattern is always the same: a throwaway container with the volume and a bind mount.

# Back up a named volume to a tarball on the host
docker run --rm \
  -v pgdata:/data:ro \
  -v "$(pwd)":/backup \
  alpine tar czf /backup/pgdata-$(date +%F).tar.gz -C /data .

# Restore into a fresh volume
docker volume create pgdata-restored
docker run --rm \
  -v pgdata-restored:/data \
  -v "$(pwd)":/backup \
  alpine tar xzf /backup/pgdata-2024-05-01.tar.gz -C /data

# Copy one volume to another
docker run --rm -v pgdata:/from:ro -v pgdata-copy:/to alpine sh -c 'cp -a /from/. /to/'

# What is in there, and how big?
docker run --rm -v pgdata:/data:ro alpine du -sh /data
docker system df -v

Registry hygiene

An unmanaged registry becomes a slow, expensive, confusing place. Four decisions fix it.

# Tag one build several ways, push once
docker buildx build \
  -t ghcr.io/org/app:sha-${GIT_SHA} \
  -t ghcr.io/org/app:main \
  --push .

# Resolve a tag to the digest you will actually deploy
docker buildx imagetools inspect ghcr.io/org/app:sha-${GIT_SHA} \
  --format '{{.Manifest.Digest}}'

# Promote by re-tagging that digest — no rebuild
docker buildx imagetools create -t ghcr.io/org/app:staging ghcr.io/org/app@sha256:9b2c...

Set a retention policy: keep all release tags, keep the last N sha- tags, expire untagged manifests after a week. Without it, build cache and dangling manifests become your largest storage line item.

Making dev and prod differences explicit

The goal is one image promoted everywhere. Where local and production must differ, put the difference in a file somebody can read, not in a developer's memory.

# Base: what is true everywhere
services:
  api:
    image: ghcr.io/org/app:${TAG:-dev}
    environment:
      LOG_FORMAT: json
    healthcheck:
      test: ['CMD-SHELL', 'curl -fsS http://localhost:8000/health || exit 1']
      interval: 30s
      start_period: 40s
    mem_limit: 512m
    restart: unless-stopped

# Local only, applied automatically
services:
  api:
    build: { context: ., target: builder }
    volumes:
      - '.:/app'
      - '/app/node_modules'
    environment:
      LOG_FORMAT: pretty
      LOG_LEVEL: debug
    command: ['uvicorn', 'app:app', '--reload', '--host', '0.0.0.0']
    ports: ['8000:8000']

docker compose up                                         # base + override
docker compose -f compose.yaml -f compose.prod.yaml up -d  # explicit, no override
docker compose -f compose.yaml config                      # what production really gets

Habits worth adopting now

Pin base image tags, and pin them narrowly. python:3.11-slim is fine; python:latest means your build changes without a commit. For anything security-sensitive, pin the digest.

One image, many environments. Everything environment-specific arrives at run time. If you need a different image per environment, your configuration is in the wrong place.

Give every long-running service a health check. It is what makes depends_on meaningful and what every orchestrator uses to decide whether to send traffic.

Set memory and CPU limits even locally. A runaway container should hit a limit, not your laptop's swap.

Add a docker history grep to CI. One line that catches a secret before it is published, permanently.

Treat docker compose down -v with suspicion. The -v deletes named volumes, which is your local database.

services:
  api:
    build: { context: ., target: runtime }
    image: ghcr.io/org/app:${TAG:-dev}      # same image, tag from the environment
    ports: ['8000:8000']
    env_file: [.env]
    healthcheck:
      test: ['CMD-SHELL', 'curl -fsS http://localhost:8000/health || exit 1']
      interval: 30s
      timeout: 3s
      start_period: 40s
      retries: 3
    deploy:
      resources:
        limits: { memory: 512M, cpus: '1.0' }
    restart: unless-stopped

Senior tips go further: the hardening pass every image should get, verifying controls rather than trusting them, keeping images fresh without unpinning them, incident playbooks for a leaked secret and a host taken down by one container, running Docker as a platform, and the cost levers that pay.

This is part three of three. It closes the series by taking every topic from Beginner and Mid one level further (each one now has a security, scale, or ownership dimension) and adds the work you own when containers are your responsibility rather than your tool.

Up to this point the questions have been about making containers work. From here they are different: what can a compromised container reach, what is inside the image you are shipping, who can prove it was built from your source, and what happens when one container tries to take the host down with it.

Where this picks up

I am starting with the isolation model, because every other decision in this track depends on understanding what a container is not.

What isolation gives you

You have known since Beginner that a container is "a process with a restricted view". That view is built from three separate kernel mechanisms, and knowing which one does what is the difference between reasoning about security and guessing at it.

Namespaces are why ps aux inside a container shows two processes and ls / shows a different filesystem. cgroups are why -m 512m works. Capabilities and seccomp are why a container cannot load a kernel module even as root.

There is no hypervisor. The kernel is shared with the host and with every other container on it.

Two consequences shape real decisions.

Capabilities are the interesting layer, because Docker already drops most of them and people rarely look at which remain. The default set still includes NET_RAW (raw sockets, so ARP and ICMP spoofing), SETUID/SETGID, CHOWN, and MKNOD. Almost no application needs any of them.

docker run --rm alpine sh -c 'apk add -q libcap; capsh --print | head -3'
docker run --rm --cap-drop ALL alpine sh -c 'ping -c1 127.0.0.1 || echo "no NET_RAW"'

If you must run untrusted code, you want a stronger boundary than a namespace. gVisor intercepts syscalls in userspace, Kata Containers and Firecracker give each container a lightweight VM, and a plain separate VM is always an option. All of them cost performance, and all of them are the right answer when the workload is somebody else's code.

Hardening a container

Five changes cover most of the realistic risk, and together they cost almost nothing at run time.

FROM python:3.11-slim

# 1. A real non-root user with a fixed numeric uid and no login shell
RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin appuser

WORKDIR /app
COPY --chown=appuser:appuser requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY --chown=appuser:appuser . .

USER 10001                        # numeric, so it survives image inspection tooling
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

docker run -d \
  --user 10001:10001 \
  --read-only \                       # 2. immutable root filesystem
  --tmpfs /tmp:rw,noexec,nosuid \     #    with writable scratch where genuinely needed
  --cap-drop ALL \                    # 3. drop every capability
  --cap-add NET_BIND_SERVICE \        #    add back only what is required
  --security-opt no-new-privileges \  # 4. block setuid escalation
  -m 512m --cpus 1 --pids-limit 200 \ # 5. bound the blast radius
  myapp:1.4.2

--read-only is the one people skip because it looks disruptive. It usually is not: most services need exactly one or two writable paths, and declaring them is a five-minute exercise that turns "the container can write anywhere" into "the container can write to /tmp". The discipline itself is valuable. If you cannot list your service's writable paths, you do not know what it does.

Rootless Docker and user namespaces

The hardening above bounds what a container can do. Rootless mode changes what "root inside the container" even means on the host, which is a different and stronger kind of protection.

Two mechanisms, often confused:

{
  "userns-remap": "default"
}

With that set, a process running as root inside a container is some high-numbered unprivileged uid, typically 100000-something, on the host. An escape lands as nobody rather than as root, which removes an entire class of consequence.

The caveats are real and you should test rather than assume. Existing volumes have ownership from before the remap and will need adjusting. Images that assume specific uid semantics can break. Bind mounts become more awkward, because the host path's ownership must line up with the mapped range.

Rootless Docker goes further: the daemon itself runs as your user, using user namespaces and a userspace network stack. Nothing in the chain runs as host root.

dockerd-rootless-setuptool.sh install
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
docker info | grep -i rootless

Secrets that never reach a layer

Mid established the mechanism: layers are additive, so anything written into one is permanent. Build-time credentials are the one case with no run-time answer, so they need their own mechanism.

# syntax=docker/dockerfile:1

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .

# The secret is mounted for this RUN only and never becomes a layer
RUN --mount=type=secret,id=pip_token \
    PIP_INDEX_URL="https://$(cat /run/secrets/pip_token)@pypi.internal/simple" \
    pip install --no-cache-dir -r requirements.txt

docker build --secret id=pip_token,env=PIP_TOKEN -t myapp:1.4.2 .
docker build --secret id=pip_token,src=./token.txt -t myapp:1.4.2 .

# Private Git dependencies without embedding a key
docker build --ssh default -t myapp:1.4.2 .

RUN --mount=type=ssh \
    pip install git+ssh://git@github.com/my-org/private-lib.git@v1.2.0

Then verify rather than assume, because the whole point is that you can check:

# Is anything sensitive recorded in the build history?
docker history --no-trunc myapp:1.4.2 | grep -iE 'token|secret|password|key'

# Inspect the actual layer contents
docker save myapp:1.4.2 | tar -tv | head -40

# Is it in the image metadata?
docker inspect myapp:1.4.2 --format '{{range .Config.Env}}{{println .}}{{end}}'

Supply chain

The question a senior gets asked is not "did it build?" but "can you prove what is in it and where it came from?" Six controls answer six distinct questions, and they compose.

# Pinned by digest: reproducible, and immune to a repointed tag
FROM python:3.11-slim@sha256:8f2c...

# Build with an SBOM and provenance attached
docker buildx build \
  --sbom=true --provenance=true \
  -t ghcr.io/org/app:sha-a1b2c3d --push .

# Scan, and fail CI on what matters
trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed ghcr.io/org/app:sha-a1b2c3d

# Sign, and verify at deploy time
cosign sign ghcr.io/org/app@sha256:9b2c...
cosign verify --certificate-identity-regexp '.*' ghcr.io/org/app@sha256:9b2c...

# Read what was attached
docker buildx imagetools inspect ghcr.io/org/app:sha-a1b2c3d --format '{{json .SBOM}}'

Pinning and patching pull in opposite directions, and you need both:

name: Weekly rebuild
on:
  schedule: [{ cron: '0 4 * * 1' }]
  workflow_dispatch:
jobs:
  rebuild:
    runs-on: ubuntu-latest
    permissions: { contents: read, packages: write, id-token: write }
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          sbom: true
          provenance: true

There is one more trust boundary worth naming, because it is easy to miss: a shared build cache is an input to your build. If a pull request from a fork can write to the same cache your main branch reads, a poisoned cache entry becomes code execution in a trusted build. Scope caches per branch or per trust level, and never restore a cache and execute its contents without thought.

Multi-architecture builds

Apple Silicon builds arm64. Most servers want amd64. Cloud ARM instances want arm64. A single-architecture image is a deployment failure waiting for the wrong machine.

docker buildx create --use --name multi
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/org/app:1.4.2 --push .

docker buildx imagetools inspect ghcr.io/org/app:1.4.2

The result is a manifest list: one tag pointing at several images, with the client automatically selecting the right one. docker pull on an ARM laptop and on an x86 server both work, from the same reference.

The cost is the part people discover late. Buildx emulates the foreign architecture with QEMU, and emulated builds are several times slower. For a compile-heavy image, minutes become tens of minutes. For anything on the critical path, build each architecture on its own native runner and merge the manifests afterwards:

# On an amd64 runner
docker buildx build --platform linux/amd64 -t ghcr.io/org/app:1.4.2-amd64 --push .

# On an arm64 runner
docker buildx build --platform linux/arm64 -t ghcr.io/org/app:1.4.2-arm64 --push .

# Then merge, from anywhere
docker buildx imagetools create -t ghcr.io/org/app:1.4.2 \
  ghcr.io/org/app:1.4.2-amd64 \
  ghcr.io/org/app:1.4.2-arm64

Resource limits and the OOM killer

Mid taught you to set limits. What happens at the boundary decides whether a memory problem is a bounded incident or an outage.

Without limits, one container consumes all host memory and the kernel's OOM killer picks a victim by a heuristic score, and not necessarily the guilty container. Your database can be the process that dies because an unrelated worker leaked memory.

docker run -d \
  -m 512m --memory-reservation 256m \
  --cpus 1.5 \
  --pids-limit 200 \
  --restart on-failure:5 \
  myapp:1.4.2

docker stats --no-stream
docker inspect --format '{{.State.OOMKilled}}' myapp     # true after a 137

With a limit in place, the kill is scoped to that container's cgroup and the verdict is recorded. That is the entire value: a diagnosable failure with a clear exit code rather than a mystery outage somewhere else on the host.

Two related failure modes worth knowing:

CPU throttling looks like slowness, not an error. A container over its --cpus quota is not killed, it is throttled, so latency rises with no log line explaining why. Check docker stats and the cgroup's throttling counters before concluding the code got slower.

Disk is a limit too, and it has no flag. A container with an unbounded log or a growing writable layer fills the host filesystem, and a full disk presents as a dozen unrelated failures across every container on the machine. Daemon-level log rotation is the fix, and it belongs in configuration rather than in each service.

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" },
  "default-ulimits": { "nofile": { "Name": "nofile", "Soft": 4096, "Hard": 8192 } },
  "live-restore": true
}

live-restore lets containers keep running through a daemon restart, which turns a Docker upgrade from an outage into a maintenance task.

Production runtime practices

Six practices, each of which prevents a class of incident rather than a specific bug.

1. One concern per containerNot literally one process, a supervisor for a worker pool is fine, but one responsibility, so it can be scaled, restarted, and logged independently. Two concerns in one container means you cannot restart one without the other.
2. Log to stdout and stderrNever to a file inside the container. Configure rotation on the daemon (max-size, max-file) or you will eventually fill a disk with JSON, and a full disk on a container host looks like a dozen unrelated failures.
3. Health checks that mean somethingA liveness check that only proves the process is alive is worthless, because Docker already knew that. Check the dependency you need, keep it cheap enough to run every thirty seconds, and do not fail it because a non-critical downstream is slow.
4. Handle SIGTERM properlyExec form, and exec "$@" in entrypoint scripts. Then drain connections on SIGTERM instead of dropping them. Confirm it: a clean stop exits 143, not 137.
5. Immutable, digest-addressable deploysDeploy :sha-a1b2c3d or a digest. A moving tag makes "what is running?" unanswerable and rollback undefined. You cannot roll back to a tag whose contents have changed.
6. Build once, promote the same artifactIf production rebuilds the image, production is running something CI never tested. Promotion is the difference between shipping your tested artifact and shipping something that resembles it.

Liveness and readiness deserve separating, because Docker has one concept and orchestrators have two:

Conflating the first two is a common and expensive mistake: if your liveness check fails whenever a downstream dependency is briefly unavailable, a dependency blip becomes a rolling restart of every one of your instances, turning a small problem into a large one.

Containers for machine learning

ML images amplify every size and reproducibility problem in this guide: a CUDA base is gigabytes before your code exists, model weights are large binary blobs that change on a different cadence than code, and the dependency graph is fragile enough that a floating tag will eventually break a build.

# syntax=docker/dockerfile:1
FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04

ENV PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=0

RUN apt-get update \
 && apt-get install -y --no-install-recommends python3.11 python3-pip \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Cache mount: ML wheels are enormous, and this keeps them out of the image
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip3 install -r requirements.txt

RUN useradd --create-home --uid 10001 appuser
COPY --chown=appuser:appuser src/ ./src/
USER 10001

# Weights arrive as a mounted volume, NOT baked into the image
ENV MODEL_PATH=/models/current
CMD ["python3", "-m", "src.serve"]

docker run -d --gpus all \
  -v model-store:/models:ro \
  -p 8080:8080 \
  --shm-size 1g \
  -m 16g --cpus 4 \
  ghcr.io/org/inference@sha256:9b2c...

Five decisions in there are the whole lesson.

Use the runtime CUDA base, not devel. The devel image carries nvcc and the full toolchain and is frequently several gigabytes larger. If you need to compile extensions, do it in a builder stage and copy the result.

Never bake model weights into the image. They make every push and pull move gigabytes, they change on a different schedule than your code, and they force an image rebuild to ship a retrained model. Mount them read-only from a volume or object store, versioned independently.

--gpus all requires the NVIDIA Container Toolkit on the host. The image contains no driver; it uses the host's. That is why the CUDA runtime version in the image must be compatible with the host driver, and why a mismatch fails at startup with a message that does not obviously say "driver".

--shm-size matters for PyTorch DataLoader. The 64 MB default shared-memory segment causes worker crashes with errors that look like anything but shared memory.

Pin everything, including CUDA and cuDNN. ML dependency graphs are fragile enough without a floating base tag moving underneath them.

Where Docker stops

Naming the boundary is itself a senior signal, and in an interview it lands better than a list of orchestrator features.

The reassuring part is that almost everything in this guide transfers:

Compose is the same model on one host, and the concepts map across almost one-to-one, so nothing you learned here gets thrown away. What an orchestrator adds is scheduling, reconciliation, and multi-host networking, not a different container model.

Running Docker as a platform

Once more than one team is building images, the highest-leverage work stops being technical and starts being about defaults. Four decisions cover most of it.

Publish base images, not documentation. A hardened FROM line gets adopted; a wiki page does not. Put the non-root user, the pinned base, the sensible ENV values, and the standard labels into an internal base image, and teams inherit all of it by changing one line.

Version base images with a moving major tag. Consumers use python-base:3.11; you release 3.11.7-2 and move the pointer. Canary one low-risk service on the exact patch tag first. Otherwise one bad base image release breaks every team simultaneously, which is a memorable way to lose their trust.

Own the registry policy. Immutable tags where the registry supports them, retention rules so old images are pruned, an internal mirror so an upstream outage is not your outage, and an admission policy that refuses unsigned or unscanned images.

Measure image health. Without numbers, "our images are fine" is an opinion:

Cost and performance levers worth knowing, roughly in order of return:

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" },
  "live-restore": true,
  "userns-remap": "default",
  "default-ulimits": { "nofile": { "Name": "nofile", "Soft": 4096, "Hard": 8192 } }
}

Debugging production under pressure

Under pressure, ordering matters more than knowledge. This sequence is designed so the cheapest, highest-information checks come first.

docker inspect api --format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}'
docker inspect api --format '{{.Image}}'
docker inspect api --format '{{index .RepoDigests 0}}'
docker events --since 30m --filter container=api
docker system df -v
docker run --rm -it --network container:api nicolaka/netshoot

Four incident shapes and the first move for each:

A secret was found in a published image. Rotate first. The image is already pulled and cached in places you do not control, so assume the credential is compromised regardless of how quickly you delete the tag. Then revoke, remove what you can reach, find the instruction that introduced it, and close the class with a BuildKit secret mount plus a docker history grep in CI. Deleting the image first and rotating later optimises for appearances.

One container took the host down. Check limits before code. A container with no memory limit will consume all host RAM and the OOM killer may take something else entirely. Confirm with docker inspect and the host's dmesg, then apply -m, --cpus, and --pids-limit to everything on that host, not just the guilty container, because the next one will be different.

Everything went red at once. Follow the timeline above. Simultaneous failure across unrelated services is almost never a code change; it is the host, the daemon, a shared base image, a registry outage, or a full disk.

An image you depend on was compromised. Find every deployment referencing it and at which digest. Revoke every credential those containers could reach, not only the ones you believe were used. Replace with a vetted digest or an internal mirror. Then close the class: digest pinning, a registry mirror, signature verification at admission, and scheduled rebuilds.

The review checklist

Take this checklist away from this level. Run it against any Dockerfile and docker run line (your own, or one you are reviewing) and it catches nearly everything covered here before it reaches production.

The complete picture

The series' final artefact: every level's topics, hardened. Nothing in it is new, and you should be able to justify every line.

# syntax=docker/dockerfile:1

# ---------- build stage: toolchain and credentials live and die here ----------
FROM python:3.11-slim@sha256:8f2c... AS builder

RUN apt-get update \
 && apt-get install -y --no-install-recommends build-essential \
 && rm -rf /var/lib/apt/lists/*

RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

WORKDIR /app
COPY requirements.txt .

# Cache mount for speed; secret mount so the token never becomes a layer
RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=secret,id=pip_token \
    PIP_INDEX_URL="https://$(cat /run/secrets/pip_token)@pypi.internal/simple" \
    pip install -r requirements.txt

# ---------- test stage: a red test cannot produce a shippable image ----------
FROM builder AS test
COPY . .
RUN ruff check . && pytest -q

# ---------- runtime stage: only what is needed to serve ----------
FROM python:3.11-slim@sha256:8f2c... AS runtime

ARG BUILD_REV=unknown
ENV APP_REV=${BUILD_REV} \
    LOG_LEVEL=info \
    PYTHONUNBUFFERED=1 \
    PATH="/opt/venv/bin:$PATH"

LABEL org.opencontainers.image.source="https://github.com/my-org/myapp" \
      org.opencontainers.image.revision="${BUILD_REV}"

RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin appuser

COPY --from=builder /opt/venv /opt/venv

WORKDIR /app
COPY --chown=appuser:appuser src/ ./src/

USER 10001
EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/health').status==200 else 1)"

CMD ["uvicorn", "src.app:app", "--host", "0.0.0.0", "--port", "8000"]

# Build with a secret, an SBOM, provenance, and a traceable tag
docker buildx build \
  --secret id=pip_token,env=PIP_TOKEN \
  --build-arg BUILD_REV="$(git rev-parse --short HEAD)" \
  --platform linux/amd64,linux/arm64 \
  --sbom=true --provenance=true \
  --cache-from type=registry,ref=ghcr.io/org/app:buildcache \
  --cache-to type=registry,ref=ghcr.io/org/app:buildcache,mode=max \
  -t ghcr.io/org/app:sha-$(git rev-parse --short HEAD) \
  --push .

# Verify before trusting
docker history --no-trunc ghcr.io/org/app:sha-abc1234 | grep -iE 'token|secret|password' || echo 'clean'
trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed ghcr.io/org/app:sha-abc1234
cosign sign ghcr.io/org/app@sha256:9b2c...

# Run hardened, by digest
docker run -d \
  --name api \
  --user 10001:10001 \
  --read-only --tmpfs /tmp:rw,noexec,nosuid \
  --cap-drop ALL --cap-add NET_BIND_SERVICE \
  --security-opt no-new-privileges \
  -m 512m --cpus 1 --pids-limit 200 \
  --restart on-failure:5 \
  -p 8000:8000 \
  --env-file /run/secrets/app.env \
  ghcr.io/org/app@sha256:9b2c...

Where the series leaves you

Across the three levels you have gone from a first docker run to owning containers as a platform. The same topics carried all the way through, each time with more depth:

You should now be able to look at a Dockerfile and a docker run line and see not just what they do but what they permit: whether the process is root, which capabilities it holds, whether the filesystem is writable, whether a secret is in a layer, whether the base image can change under you, whether the deploy reference can move, whether the health check means anything, and whether one container can take the host with it.

Carry that review instinct out of here, because, as with CI/CD pipelines, most container incidents are prevented at review time rather than at runtime.

Part three of three. A cumulative review of the entire series: foundations, image and runtime machinery, and the security and platform work a senior owns, organised by topic rather than by level. About fifty minutes. Fast review first, common questions at the end.

Part one: foundations

Docker packages an application with its runtime and dependencies into an immutable image. A container is a running instance: a process on the host isolated by namespaces and cgroups, not a virtual machine. The artifact that passed CI is the artifact that runs in production.

Container versus VM: shared kernel, milliseconds, tens of MB, isolated by kernel features. A VM boots a full guest OS in tens of seconds, costs gigabytes, and is isolated by a hypervisor. Container isolation is weaker, and you should say so unprompted.

Image versus container: read-only template versus running instance with a thin writable layer. One image, many containers. Anything outside a volume dies with docker rm.

A container lives as long as its main process. EXPOSE publishes nothing. RUN is build time, CMD is run time. Inside a container, bind 0.0.0.0 and log to stdout.

Exit codes and the first five commands

The traps, and their shared causes

Three ideas explain most beginner failures: a container is one process, the writable layer is temporary, and build time is not run time.

Part two: image and runtime machinery

Layers and the cache

A layer is reused when its cache key is unchanged, and once one is invalidated every layer after it rebuilds.

Hence two facts: RUN apt-get update alone reuses a stale index, so update && install && rm -rf /var/lib/apt/lists/* must be one instruction; and layers are additive, so deleting neither shrinks nor hides.

Multi-stage and size

FROM node:20 AS builder
RUN npm ci && npm run build

FROM node:20-slim
COPY --from=builder /app/dist ./dist
USER node
CMD ["node", "dist/server.js"]

Only what you COPY --from crosses the boundary. --target stops at a stage; a test stage makes a red test fail the image build; COPY --from= also accepts an image reference.

BuildKit mounts

# syntax=docker/dockerfile:1
RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=secret,id=pip_token \
    PIP_INDEX_URL="https://$(cat /run/secrets/pip_token)@pypi.internal/simple" \
    pip install -r requirements.txt

A cache mount persists across builds without entering the image, surviving layer invalidation. A secret mount makes a credential available to one RUN without it ever becoming a layer. --ssh default does the same for private Git dependencies.

Config, networking, volumes

Precedence: -e → --env-file → ENV. The default bridge has no DNS; a user-defined network resolves container names, aliases, and Compose service names via an embedded resolver. localhost inside a container means that container; host.docker.internal reaches the host.

Volumes: named for state (Docker-managed, portable, correct ownership), bind for development (host-path dependent, UID-sensitive), anonymous to mask a subpath under a bind mount, tmpfs for in-memory scratch, :ro for config. Back up with a throwaway container plus tar; use pg_dump for anything transactional.

Health, signals, limits

HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD curl -fsS http://localhost:8000/health || exit 1

People forget --start-period. The check runs inside the container and its exit code is the result, so curl -f matters: plain curl exits 0 on a 500.

Limits: -m is a hard ceiling (exceeding it means SIGKILL and 137), --cpus throttles rather than fails, --pids-limit caps processes. Without limits the OOM killer may take something else. Older JVMs and Node builds read the host's memory rather than the cgroup, so a container can OOM at 512 MB while idle.

Compose, registries, promotion

depends_on waits for started, not ready. Fix it with a health check plus condition: service_healthy, and retries in the app. compose.override.yaml applies automatically, so pass -f explicitly in CI. docker compose config prints the merged file and settles most disputes.

A tag is a mutable pointer; only a digest is immutable. Deploy :sha-a1b2c3d or a digest, keep :latest for humans, and build once, promote the same artifact. If production rebuilds, production runs something CI never tested. In CI, layer caching does nothing without an exported backend: cache-to type=gha,mode=max.

Part three: security, supply chain, and scale

The isolation model

There is no hypervisor. Your container shares one kernel with the host and every other container.

Docker's default capability set still includes NET_RAW, SETUID, CHOWN, and MKNOD, which most applications never use.

Hardening, in five controls

docker run -d \
  --user 10001:10001 \
  --read-only --tmpfs /tmp:rw,noexec,nosuid \
  --cap-drop ALL --cap-add NET_BIND_SERVICE \
  --security-opt no-new-privileges \
  -m 512m --cpus 1 --pids-limit 200 \
  ghcr.io/org/app@sha256:9b2c...

Three flags that hand over the machine: --privileged, mounting /var/run/docker.sock, and --net=host. Each needs a written justification, never a debugging convenience left in the file.

userns-remap maps container root to an unprivileged host uid; rootless Docker runs the daemon as your user. Both remove a class of escape consequence, both need testing against existing volumes.

Supply chain

docker buildx build --sbom=true --provenance=true -t ghcr.io/org/app:sha-a1b2c3d --push .
trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed ghcr.io/org/app:sha-a1b2c3d
cosign sign ghcr.io/org/app@sha256:9b2c...

Gate on fixable HIGH and CRITICAL only. Failing on unfixable findings trains everyone to ignore the gate. Pinning plus scheduled rebuilds is the working combination; pinning alone freezes vulnerabilities in place. An image built four months ago is a bigger problem than today's scan report. A shared build cache is an input to your build: a poisoned entry is code execution.

Multi-arch, runtime, ML

Apple Silicon builds arm64; most servers want amd64. docker buildx build --platform linux/amd64,linux/arm64 produces a manifest list: one tag, several images, client-selected. QEMU emulation is several times slower, so build natively per architecture and merge manifests for anything on the critical path. "exec format error", or unexplained slowness, points here first.

Production practices: one concern per container; stdout logging with daemon-level rotation; health checks that test the dependency you need; SIGTERM handled and drained; immutable digest deploys; build once and promote. Orchestrators split Docker's single HEALTHCHECK into liveness, readiness, and startup probes. Conflate liveness with dependency health and a downstream blip turns into a restart storm.

ML images: use the CUDA runtime base not devel; never bake model weights into a layer, mount them read-only, versioned separately; --gpus all needs the NVIDIA Container Toolkit and a CUDA runtime compatible with the host driver; raise --shm-size for PyTorch DataLoader; pin everything.

Where Docker stops

Compose is enough for one host, a handful of services, and acceptable deploy downtime. You need an orchestrator for multi-host scheduling, rolling deploys with rollback, autoscaling, cross-host service discovery, and declarative reconciliation. Most of what you already know transfers: the same OCI images and digests, HEALTHCHECK thinking becomes probes, -m/--cpus become requests and limits, non-root and capabilities become a security context, -e becomes ConfigMaps and Secrets, named volumes become PVCs.

The review checklist

Automate the mechanical rows with hadolint, trivy config, and a docker history grep in CI. Reserve human review for judgement: is the capability set right, does the health check test the right thing, is that --privileged necessary.

Common interview questions

1. What does container isolation consist of?Three separate mechanisms: namespaces give separate views of PIDs, mounts, network, hostname, users, and IPC; cgroups impose limits on CPU, memory, PIDs, and I/O; capabilities, seccomp, and AppArmor or SELinux restrict which privileged operations the process may perform. There is no hypervisor, so the process runs on the host's kernel.
2. Is a container a security boundary?It is a real boundary, weaker than a VM, and not sufficient for untrusted code. Root inside is root on the host kernel unless you use userns-remap or a rootless daemon, so a kernel vulnerability or a careless mount is an escape path. For untrusted workloads, use gVisor, Kata, Firecracker, or a separate VM.
3. Harden a container for me, out loud.Non-root numeric USER; --read-only root filesystem with a tmpfs for declared writable paths; --cap-drop ALL then add back only what is needed; no-new-privileges; and memory, CPU, and PID limits. Then verify each one refuses something. A control you have never watched block anything is decoration.
4. Which flags would you refuse in review?--privileged disables most of the isolation. Mounting /var/run/docker.sock gives the container control of the daemon, which is root-equivalent on the host. --net=host removes network isolation. Each is occasionally justified, and each needs a written reason rather than being left behind after debugging.
5. How do you use a credential at build time without leaking it?A BuildKit --mount=type=secret, or --ssh default for private Git dependencies. Never ARG or ENV, because both are image metadata, and never COPY then rm, because layers are additive. Then verify with a docker history --no-trunc grep and by extracting the layers with docker save.
6. A secret was found in a published image. What is your first move?Rotate. The image is already pulled and cached in CI runners, developer machines, and registry mirrors you do not control, so assume the credential is compromised regardless of how fast you delete the tag. Then revoke, clean up what you can reach, find the instruction that introduced it, and close the class with a secret mount plus a CI check.
7. Walk me through your supply-chain controls.Digest-pin the base so it cannot move; attach an SBOM so you know what is inside; scan and gate on fixable HIGH and CRITICAL only; attach provenance so the producing workflow and commit are verifiable; sign with cosign; and enforce an admission policy that refuses anything unsigned. Then rebuild on a schedule, because pinning alone freezes vulnerabilities in place.
8. Why gate on fixable findings only?Because failing the build on vulnerabilities with no available patch teaches the team to ignore scan output, which is worse than not scanning. Gate on what you can act on, track the rest, and treat image age as the metric that correlates with exposure.
9. How do pinning and patching coexist?Digest-pin for reproducibility, then rebuild on a schedule and let Dependabot bump the pinned digest by pull request. Pinning without rebuilding is frozen vulnerabilities; a floating tag without pinning is an unreproducible build. You need both halves.
10. Is a shared build cache a trust boundary?Yes. A cache is an input to your build, so if a fork's pull request can write to the cache your trusted branch reads, a poisoned entry gives the attacker code execution in a privileged build. Scope caches per branch or trust level, and never restore and execute cache contents without thought.
11. Explain multi-architecture builds and their cost.buildx --platform linux/amd64,linux/arm64 produces a manifest list: one tag, several images, with the client selecting. Emulated cross-builds via QEMU are several times slower, so for anything on the critical path build each architecture on a native runner and merge manifests with imagetools create.
12. A container is OOM-killed at 512 MB while apparently idle.The runtime is reading the host's memory rather than the cgroup limit and sized its heap for the whole machine. Classic with older JVMs and Node. Use a container-aware runtime, or set --max-old-space-size to roughly 75% of the limit.
13. Why set limits at all if the container just dies?Because without them the OOM killer chooses by score and may kill something else entirely: your database rather than the leaking worker. A limit turns an unbounded host incident into a scoped, recorded, diagnosable failure with exit 137 and OOMKilled: true.
14. Liveness versus readiness: why does it matter?Liveness asks "is this wedged and in need of a restart"; readiness asks "should it receive traffic right now". If your liveness check fails when a downstream dependency blips, every instance restarts at once and a small problem becomes an outage. Docker has one HEALTHCHECK; orchestrators split it, and the distinction is where people get burned.
15. How do you make "what is running?" answerable?Deploy digests rather than tags, label images with their source commit and revision, and expose that revision on a status endpoint. Every incident starts with that question, and the difference between a ten-second and a ten-minute answer is the difference between a short and a long incident.
16. How would you containerise a machine-learning service?CUDA runtime base rather than devel; cache mounts for the enormous wheels; weights mounted read-only from a volume or object store and versioned separately, never baked into a layer; --gpus all with the NVIDIA Container Toolkit on the host and a CUDA runtime compatible with the host driver; raised --shm-size for DataLoader workers; and everything pinned, because ML dependency graphs are fragile.
17. Why not bake model weights into the image?Because weights are data, not code. Baking them means every retrain pushes gigabytes, every deploy pulls them again, and the model version becomes coupled to the code version, so rollback is ambiguous. Mount them and version them independently.
18. When do you need an orchestrator, and what carries over?When you have more than one host, need rolling deploys with automatic rollback, autoscaling, cross-host service discovery, or declarative reconciliation. Everything else carries over: the same OCI images and digests, health-check thinking as probes, cgroup limits as requests and limits, non-root and capabilities as a security context, environment and mounted config as ConfigMaps and Secrets, named volumes as PVCs.
19. Would you recommend Swarm?For a small internal multi-host deployment it is simpler and defensible. As a general recommendation, no: the ecosystem and industry momentum are with Kubernetes, and choosing Swarm means owning that gap. Be ready for the follow-up either way.
20. How would you run Docker for sixty engineers?Publish hardened base images rather than documentation, because a FROM line gets adopted and a wiki page does not. Version them with a moving major tag and canary the exact patch first. Own registry policy: immutable tags, retention, an internal mirror, admission control. Measure image size, image age, fixable findings, and build duration, because without numbers "our images are fine" is an opinion.
21. What is the failure mode of a shared base image?A team needs one package, cannot get it upstream quickly, and forks. Six months later there are eleven variants and no standard. The fix is turnaround time on upstream requests, not policy. If a reasonable change takes two weeks, forking is rational and you will lose.
22. Everything went red at once. Walk me through it.Blast radius first: one container or all of them? Simultaneous failure across unrelated services means the host, the daemon, a shared base image, a registry, or a full disk, not my diff. Then exit codes and the OOM flag, then confirm which digest is running, then host disk and inodes, then network from inside the namespace with a netshoot sidecar. Afterwards, pin what moved and push the missing limit or probe into the shared base image.
23. What do you look for reviewing a Dockerfile?Not what it does, but what it permits. Is the base pinned, is the process root, which capabilities does it hold, is the filesystem writable, is a secret in a layer, can the base change under us, can the deploy reference move, does the health check mean anything, and can one container take the host with it. Most container incidents are prevented at review time rather than at runtime.