Linux command: docker

1. The Basics

Docker packages an application together with everything it needs to run, and then starts it as an ordinary process on your machine that thinks it has the machine to itself. That is the whole idea. Everything else is detail.

1.1 The Simplest Possible Use

One command proves the whole installation works:

$ docker run hello-world
Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

That message is worth reading properly, because it lists the four things that happen every single time you type docker run, and three of them are not obvious.

1.2 Image, Container, Registry

Three words carry most of the meaning, and mixing them up is the source of half of all Docker confusion.

You can make many containers from one image, and they do not affect each other. Here are two containers from the same alpine image, where one edits a file:

$ docker run -d --name c1 alpine:3.20 sleep 300
$ docker run -d --name c2 alpine:3.20 sleep 300
$ docker exec c1 sh -c 'echo "changed by c1" > /etc/motd'

$ docker exec c1 cat /etc/motd
changed by c1

$ docker exec c2 cat /etc/motd
Welcome to Alpine!                 # untouched

$ docker run --rm alpine:3.20 cat /etc/motd
Welcome to Alpine!                 # the image itself never changed

Docker calls this copy on write. The image layers stay shared and read-only, and each container gets its own private layer that records only what it changed. You can see exactly what a container changed:

$ docker diff c1
C /etc
C /etc/motd                        # C changed, A added, D deleted

The kernel feature doing this is a union filesystem. Docker's default storage driver is called overlay2, and it builds each container's filesystem out of OverlayFS directories that you can look at directly:

$ docker inspect -f '{{json .GraphDriver}}' c1
Name: overlay2
  LowerDir  = /var/lib/docker/overlay2/df4d83b6.../diff:...   # the image layers
  UpperDir  = /var/lib/docker/overlay2/df4d83b6.../diff       # this container
  MergedDir = /var/lib/docker/overlay2/df4d83b6.../merged     # what it sees
  WorkDir   = /var/lib/docker/overlay2/df4d83b6.../work

The read-only image layers are the lower directories, the container's private layer is the upper one, and the container sees the merged view of the two. Starting a container therefore does not copy a root filesystem, which is why it takes about a fifth of a second rather than the minute a virtual machine needs:

$ time docker run --rm alpine:latest true
0.17 s

There is a cost hiding in that design, and it is worth knowing before you meet it. When a container writes to a file that lives in a lower layer, OverlayFS must first copy the whole file up into the writable layer. Not the changed part: the whole file.

# an image carrying one 200 MB file
$ printf 'FROM alpine:latest\nRUN dd if=/dev/zero of=/data.bin bs=1M count=200\n' > Dockerfile
$ docker build -t cowdemo:1 .

$ docker run -d --name cow1 cowdemo:1 sleep 300
$ docker ps -s --format '{{.Names}} {{.Size}}'
cow1 0B (virtual 218MB)            # the writable layer is empty

$ docker exec cow1 sh -c 'echo x >> /data.bin'       # append two bytes
$ docker ps -s --format '{{.Names}} {{.Size}}'
cow1 210MB (virtual 427MB)         # the whole file was copied up

Two bytes cost 210 MB. For source code and configuration this never matters. For a database file, a log file or a large upload it matters enormously, and it is one of the concrete reasons that data belongs in a volume (section 5.1) rather than in the container's own filesystem. A volume is a normal directory on the host, mounted straight in, with no layering and no copy-up.

1.3 A Container Is a Process, Not a Machine

This is the single most useful thing to understand, and almost every beginner gets it wrong. A container is not a small virtual machine. There is no second kernel, no boot process, no BIOS. A container is a normal Linux process that the kernel has been asked to lie to.

Start a container and look inside it:

$ docker run -d --name demo alpine:3.20 sleep 600
$ docker exec demo ps -ef
PID   USER     TIME  COMMAND
    1 root      0:00 sleep 600

The container is convinced it is process number 1 on an otherwise empty machine. Now look at the same process from the host:

$ docker top demo
UID       PID      PPID     C  STIME  TTY  TIME      CMD
root      438607   438586   0  19:42  ?    00:00:00  sleep 600

$ ps -ef | grep "sleep 600"
root      438607   438586   0  19:42  ?    00:00:00  sleep 600

It is just a process, with a perfectly ordinary process ID, visible in ps like anything else. And it runs on your kernel, not on one of its own:

$ uname -r
6.11.0-29-generic

$ docker exec demo uname -r
6.11.0-29-generic                  # the same kernel, because there is only one

Two kernel features do all the work. Namespaces give the process a private view of one part of the system: its own process list, its own network interfaces, its own hostname, its own mount table. Control groups (cgroups) put a ceiling on how much CPU, memory and I/O it may use. You can inspect the namespaces a container was put into:

$ docker run --rm alpine:3.20 ls -l /proc/self/ns/
pid    -> pid:[4026533329]         # private
net    -> net:[4026533332]         # private
mnt    -> mnt:[4026532489]         # private
uts    -> uts:[4026532490]         # private (this is the hostname)
user   -> user:[4026531837]        # NOT private: same as the host

$ ls -l /proc/self/ns/user
user   -> user:[4026531837]        # identical number

Notice the last one. By default Docker does not give a container its own user namespace, which means root inside the container is the same root the host knows. Section 7.4 shows what that costs you, and how userns-remap closes it.

The right mental model: a container is one process, fenced off by namespaces and bounded by a cgroup. Docker did not invent that. Docker made it a one-line command.

1.4 The Client and the Daemon

The docker you type is only a client. It does nothing itself. It sends HTTP requests over a Unix socket to a background service, dockerd, which owns every image, container, volume and network on the machine.

$ ls -l /var/run/docker.sock
srw-rw---- 1 root docker 0 Aug 21 09:48 /var/run/docker.sock

You can talk to it yourself, without the Docker CLI at all:

$ curl -s --unix-socket /var/run/docker.sock http://localhost/version
{"Platform":{"Name":"Docker Engine - Community"},"Components":[{"Name":"Engine",
"Version":"28.1.1","Details":{"ApiVersion":"1.49","Arch":"amd64", ...

Two consequences follow from that single socket, and both matter. First, "Docker is slow to start" usually means the daemon is doing something, not the CLI. Second, and much more important: that socket is owned by root and the group docker. Anyone in that group can ask the daemon to do anything root can do. Section 7.4 demonstrates it.

The daemon is not the end of the chain either. Modern Docker is four programs, and you can watch the handover by following a container's parent processes:

$ docker inspect -f '{{.State.Pid}}' demo
455660

$ ps -o pid,ppid,comm -p 455660
    PID    PPID COMMAND
 455660  455639 sleep

$ ps -o pid,comm,args -p 455639
 455639 containerd-shim  /usr/bin/containerd-shim-runc-v2 -namespace moby -id e18f2f...

Each piece has one job:

The detail worth noticing is what is not in that process tree. There is no runc and no dockerd above your container, because runc finishes its work and leaves, and the shim is a child of init rather than of the daemon:

$ ps -o pid,ppid,comm -C dockerd -C containerd
    PID    PPID COMMAND
   3249       1 containerd         # both are ordinary services,
   3680       1 dockerd            # started by systemd, side by side

That layout is what makes a container's life independent of the daemon's: since the shim owns the process and answers to init, dockerd can go away and come back without the container needing to notice. It is also why Kubernetes could drop dockershim and talk to containerd directly (section 3) without changing a single image. Docker is the top two boxes of a five-box stack, and the bottom three are shared with everyone else.

Whether containers actually survive a daemon restart is a separate setting, and the default catches people out:

$ docker info | grep "Live Restore"
 Live Restore Enabled: false        # containers stop when dockerd stops

Set "live-restore": true in /etc/docker/daemon.json on a server, and a daemon upgrade stops being an outage.

3. A Short History

Docker did not invent containers. Unix had chroot in 1979, FreeBSD had jails in 2000, Solaris had Zones in 2005, and Linux had LXC from 2008 built on the namespaces and cgroups that had been landing in the kernel for years. All the pieces existed. What did not exist was a way for a normal developer to use them without becoming a kernel expert.

Docker started as an internal tool at dotCloud, a platform-as-a-service company. In March 2013 it was shown publicly for the first time at PyCon in Santa Clara and released as open source. It was not a new capability. It was a package format, a registry and a command line wrapped around capabilities Linux already had, and that turned out to be the missing piece.

Two entries in that table explain confusion you will still meet in 2026. The Kubernetes one produced a wave of "Kubernetes is dropping Docker" headlines that frightened people unnecessarily: what was dropped was a translation shim, not the image format, and every image built with Docker still runs. The Compose one is why half the tutorials on the internet write docker-compose up with a hyphen and half write docker compose up with a space. The space is the current one.

Docker's real achievement was not technical, it was standardisation. Because of the OCI, an image you build today runs under Docker, Podman, containerd, CRI-O and Kubernetes without changes. The box is standard, whatever you put in it.

5. Moderate Use Cases

5.1 Keeping Data: Volumes and Bind Mounts

Everything a container writes to its own filesystem disappears when you docker rm it. For a database, that is a catastrophe waiting for a Tuesday. Docker offers two ways to keep data, and they are not interchangeable.

There is one behavioural difference that catches everyone exactly once. A named volume that is empty gets pre-filled from the image. A bind mount hides whatever the image had at that path:

$ docker volume create demo-vol
$ docker run --rm -v demo-vol:/etc alpine:3.20 sh -c 'ls /etc | wc -l'
36                                 # the image's /etc was copied in

$ mkdir /tmp/empty
$ docker run --rm -v /tmp/empty:/etc alpine:3.20 sh -c 'ls /etc | wc -l'
3                                  # the image's /etc is hidden

That is the mechanism behind "I mounted my code and now the container cannot find its dependencies". You bind-mounted your project over a directory that the image had already populated during the build, and the build's work is still there, just covered up.

The second surprise is ownership. A container runs as root by default, so the files it creates on a bind mount belong to root on your host:

$ docker run --rm -v /tmp/uid:/data alpine:3.20 touch /data/from-container
$ ls -ln /tmp/uid/
-rw-r--r-- 1 0 0 0 Aug 23 19:43 from-container      # owned by UID 0

$ id -u
1000                               # but you are UID 1000

The fix is to tell Docker which user to be:

$ docker run --rm --user "$(id -u):$(id -g)" -v /tmp/uid:/data \
    alpine:3.20 touch /data/from-me
$ ls -ln /tmp/uid/
-rw-r--r-- 1 1000 1000 0 Aug 23 19:48 from-me       # yours

Useful volume commands:

$ docker volume ls
$ docker volume inspect mydata     # where it lives on disk
$ docker volume rm mydata
$ docker run --rm -v mydata:/data -v "$PWD:/backup" alpine:3.20 \
      tar czf /backup/mydata.tar.gz -C /data .      # back a volume up

5.2 Networks and Name Resolution

Containers on the same Docker network can reach each other by name, which is how a web container finds its database without anyone knowing an IP address. But this only works on a user-defined network, not on the default bridge that plain docker run uses:

$ docker run -d --name n1 alpine:3.20 sleep 300
$ docker run --rm alpine:3.20 ping -c1 n1
ping: bad address 'n1'             # default bridge: no DNS

$ docker network create mynet
$ docker run -d --name n2 --network mynet alpine:3.20 sleep 300
$ docker run --rm --network mynet alpine:3.20 ping -c1 n2
64 bytes from 172.19.0.2: seq=0 ttl=64 time=0.054 ms      # works

The resolution is done by a small DNS server that Docker runs inside every container on a user-defined network:

$ docker run --rm --network mynet alpine:3.20 cat /etc/resolv.conf
nameserver 127.0.0.11              # Docker's embedded resolver
search .
options edns0 trust-ad ndots:0

This is one of the strongest reasons to use Compose (section 5.7): it creates a network for you, so service names just work.

Two more things to know about container networking:

• localhost inside a container is the container. An application configured to reach a database at 127.0.0.1:3306 will fail inside a container, because the database is a different container. Use the service name.
• To reach the host from a container on Linux, add --add-host=host.docker.internal:host-gateway, then connect to host.docker.internal. On Docker Desktop that name exists already.

5.3 Environment Variables

Configuration goes in through the environment, which is how the same image can serve development and production:

$ docker run -d -e MYSQL_ROOT_PASSWORD=secret mariadb:10.6
$ docker run -d --env-file ./.env myapp:1.0       # read many at once
$ docker exec web printenv | sort                  # see what a container got

Two warnings. Anything you pass with -e is visible in docker inspect to anyone who can talk to the daemon, so it is not a secret store. And anything you bake in with ENV in a Dockerfile is in the image permanently, for everyone who pulls it. Section 7.5 shows how visible that really is.

5.4 Writing a Dockerfile

A Dockerfile is a list of instructions. Each one produces a layer, and the result is an image.

FROM php:8.3-fpm-alpine            # the base image to start from

WORKDIR /var/www/html              # default directory for later steps

RUN apk add --no-cache icu-dev \
 && docker-php-ext-install intl pdo_mysql

COPY composer.json composer.lock ./     # dependencies first (see 6.1)
RUN composer install --no-dev --optimize-autoloader

COPY . .                                # then the application code

USER www-data                      # stop being root (see 6.4)

EXPOSE 9000                        # documentation, not a firewall rule

CMD ["php-fpm"]

The instructions you will use nearly every time:

EXPOSE deserves a special mention because it disappoints people. It does not open a port. It records, in the image metadata, which port the application listens on, so that humans and tools can read it. Only -p at run time actually publishes anything.

ENTRYPOINT and CMD together are the other common confusion. The rule: ENTRYPOINT is the program, CMD is the default arguments, and anything you type after the image name on the command line replaces CMD.

ENTRYPOINT ["ping"]
CMD ["-c", "3", "localhost"]

$ docker run myping                # runs: ping -c 3 localhost
$ docker run myping -c 1 8.8.8.8   # runs: ping -c 1 8.8.8.8

Both accept two syntaxes, and the difference is real. The exec form CMD ["ping", "localhost"] runs the program directly. The shell form CMD ping localhost wraps it in /bin/sh -c, which means shell features work but the shell becomes part of the picture:

# two images whose CMD differs only in its form
$ cat Dockerfile.shell             $ cat Dockerfile.exec
FROM alpine:3.20                   FROM alpine:3.20
CMD echo "hello $NAME"             CMD ["echo","hello $NAME"]

$ docker run --rm -e NAME=peter demo:shell
hello peter                        # a shell ran it, so $NAME expanded

$ docker run --rm -e NAME=peter demo:exec
hello $NAME                        # no shell involved, nothing expanded it

Use the exec form by default. Use the shell form only when you genuinely need a pipe, a redirect or a variable, and understand section 7.2 before you do.

5.5 Building and Tagging

$ docker build -t myapp:1.0 .      # -t for tag; the . is the build context
$ docker build -t myapp:1.0 -t myapp:latest .
$ docker build -f docker/Dockerfile.prod -t myapp:prod .
$ docker build --no-cache -t myapp:1.0 .        # ignore the cache entirely

That final . is not "here", it is the build context: the directory that gets packed up and sent to the build engine. Section 6.2 explains why that matters a great deal.

Tag with real version numbers, not just latest. A tag is a movable label, so myapp:latest means "whatever I last pushed", which is exactly the information you need when a deployment goes wrong and exactly the information a moving tag cannot give you.

5.6 Restart Policies

Containers exit. Applications crash, the daemon restarts, the server reboots. A restart policy tells Docker what to do about it:

$ docker run -d --restart unless-stopped --name web nginx:latest

unless-stopped is the right default for a service. It survives reboots, and it respects your decision when you stop something on purpose. Docker uses an increasing delay between attempts, so a container that crashes on start does not spin the CPU:

$ docker inspect -f 'restarts={{.RestartCount}} status={{.State.Status}}' r1
restarts=3 status=running

5.7 docker compose

Once you have three containers, typing docker run with fifteen flags each becomes a memory test. Compose puts the whole set in one file:

services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./public_html:/usr/share/nginx/html:ro
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: mariadb:10.6
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MARIADB_DATABASE: joomla
    volumes:
      - dbdata:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  dbdata:

$ docker compose up -d             # build if needed, create, start
$ docker compose ps
$ docker compose logs -f web       # logs of one service
$ docker compose exec web sh       # a shell in one service
$ docker compose down              # stop and remove containers and network
$ docker compose down -v           # ... and delete the named volumes too

Compose names everything after the project, which is the directory name unless you override it with -p:

$ docker compose up -d
$ docker compose ps
NAME           IMAGE          SERVICE   STATUS
comp-cache-1   alpine:3.20    cache     Up 8 seconds
comp-web-1     nginx:latest   web       Up 8 seconds (healthy)

$ docker network ls | grep comp
6d7ac0548fc6   comp_default   bridge    local

Note the two payoffs. The containers share a network called comp_default, so web and cache can reach each other by service name with no configuration at all. And docker compose ps reports health, which plain docker ps also does but which almost nobody sets up outside Compose.

The one detail worth memorising: docker compose down removes containers and networks but keeps named volumes. Only down -v deletes them:

$ docker compose down
$ docker volume ls | grep comp
local     comp_dbdata                  # your database survived

$ docker compose down -v
 Volume comp_dbdata  Removed          # your database did not

That default is deliberate and it is the right one. It also means down -v is a command to type slowly.

7. Something Most Users Do Not Know

7.1 Your Container Is in the Host's Process List

Section 1.3 showed it, but the consequences are worth spelling out. A container is a host process, so every ordinary Linux tool works on it. You do not need docker exec to investigate a container that has stopped responding:

$ docker inspect -f '{{.State.Pid}}' web
438607

$ sudo ls -l /proc/438607/root/    # the container's filesystem, from the host
$ sudo cat /proc/438607/environ | tr '\0' '\n'
$ sudo strace -p 438607            # trace its system calls
$ sudo nsenter -t 438607 -a sh     # enter its namespaces without Docker

That last one is the emergency door. If the Docker daemon itself is unwell, nsenter still puts you inside the container, because the namespaces belong to the kernel and not to Docker.

7.2 PID 1 Ignores SIGTERM, Which Is Why Stopping Takes Ten Seconds

Time a stop:

$ docker run -d --name demo alpine:3.20 sleep 600
$ time docker stop demo
real    0m10.093s

$ docker inspect -f 'exit={{.State.ExitCode}}' demo
exit=137                           # 128 + 9: it was SIGKILLed

docker stop sends SIGTERM, waits ten seconds, then sends SIGKILL. Almost every container takes the full ten, and the reason is a Linux rule that has nothing to do with Docker: the kernel does not apply default signal actions to PID 1. An ordinary process that ignores SIGTERM dies anyway, because the default action is to terminate. PID 1 has no default action, so a signal it does not explicitly handle is simply discarded.

$ docker run -d --name s1 alpine:3.20 sleep 300
$ docker kill -s TERM s1
$ docker inspect -f 'running={{.State.Running}}' s1
running=true                       # it shrugged off the signal

Give the same process a handler and the ten seconds disappear:

$ docker run -d --name g1 alpine:3.20 sh -c \
    'trap "echo caught SIGTERM; exit 0" TERM; while true; do sleep 1; done'
$ time docker stop g1
real    0m1.055s

$ docker logs g1
caught SIGTERM
$ docker inspect -f 'exit={{.State.ExitCode}}' g1
exit=0                             # a clean shutdown

This is not a cosmetic issue. Ten seconds of delay on every container is annoying; a database that is SIGKILLed instead of shut down cleanly is a corrupted database. If you write the application, handle SIGTERM. If you do not, section 7.3 has the general fix. In the meantime you can shorten or lengthen the grace period with docker stop -t 30, or set it per image with STOPSIGNAL.

7.3 Zombies, and What --init Is Actually For

PID 1 has a second job besides handling signals: adopting orphaned processes and reaping them when they exit. A real init does this. sleep, node and python do not. Watch a zombie appear:

$ docker run -d --name s2 alpine:3.20 sh -c 'sleep 300 & sleep 300'
$ docker exec s2 ps -ef
PID   USER     TIME  COMMAND
    1 root      0:00 sleep 300
    7 root      0:00 sleep 300

$ docker exec s2 sh -c 'kill -TERM 7'
$ docker exec s2 ps -ef
PID   USER     TIME  COMMAND
    1 root      0:00 sleep 300
    7 root      0:00 [sleep]                # defunct, never reaped

Process 7 is dead but its entry cannot be removed, because PID 1 never calls wait() for it. In a short-lived container this is harmless. In a long-running one that spawns child processes, the table fills up. Notice also that the SIGTERM which PID 1 ignored killed process 7 immediately: the same signal, the same binary, a different outcome purely because of the process ID.

The fix is one flag:

$ docker run --rm --init alpine:3.20 ps -ef
PID   USER     TIME  COMMAND
    1 root      0:00 /sbin/docker-init -- ps -ef
    7 root      0:00 ps -ef

--init puts a tiny real init (tini) at PID 1. It reaps zombies and it forwards signals to your process, so the process gets SIGTERM at a PID where the default action still applies. In Compose it is init: true. Use it for anything that starts child processes, and for any image you did not write.

7.4 Membership of the docker Group Is Root Access

Adding yourself to the docker group so you can skip sudo is the first thing most people do. It is worth understanding what you granted yourself.

$ id -nG
pe7er adm cdrom sudo dip plugdev users lpadmin docker

$ ls /root
ls: cannot open directory '/root': Permission denied

$ docker run --rm -v /:/host:ro alpine:3.20 ls /host/root
Desktop
snap

The same user, one second apart, one command. The daemon runs as root, it happily mounts any host path you name, and the container is root, so it reads anything. Replace :ro with write access and you can edit /etc/sudoers, add an SSH key to /root/.ssh, or install a systemd unit.

Docker documents this honestly: the docker group grants privileges equivalent to root. It is a reasonable trade on your own laptop. It is a decision to make consciously on a shared server, where "give the deploy user Docker access" and "give the deploy user root" are the same sentence. The mitigations are rootless mode, or Podman, or requiring sudo docker so that the privilege is at least visible in the audit log.

There is a fourth mitigation, and it is the one that closes the specific hole from section 1.3, where the container's user namespace turned out to be the host's. The daemon can be told to give containers their own:

$ cat /etc/subuid
pe7er:100000:65536                 # 65536 IDs, starting at 100000

# /etc/docker/daemon.json
{ "userns-remap": "pe7er" }

With that set, root inside a container (UID 0) is mapped to UID 100000 on the host. A container that breaks out finds itself as an unprivileged account that owns nothing, and files it writes to a bind mount are owned by 100000 rather than by root. The price is real, which is why it is not the default: bind mounts need their ownership adjusted to match the mapped range, some images that expect a specific UID break, and containers cannot share namespaces with the host. Turn it on for a server that runs other people's containers. Leave it off for a development laptop, and simply know that root in the container is root.

7.5 Build Arguments and ENV Live in the Image Forever

A common pattern for a private dependency is to pass a token at build time. It does not do what people think:

FROM alpine:3.20
ARG API_TOKEN
RUN echo "using token $API_TOKEN" > /tmp/build.log
ENV DB_PASSWORD=hunter2

$ docker build --build-arg API_TOKEN=s3cr3t-value -t leakdemo:1 .

$ docker history --no-trunc leakdemo:1 --format '{{.CreatedBy}}'
ENV DB_PASSWORD=hunter2
RUN |1 API_TOKEN=s3cr3t-value /bin/sh -c echo "using token $API_TOKEN" ...
ARG API_TOKEN=s3cr3t-value

$ docker image inspect leakdemo:1 -f '{{json .Config.Env}}'
["PATH=/usr/local/sbin:...","DB_PASSWORD=hunter2"]

Both secrets are in the image metadata, readable by anyone who pulls it, and docker history does not even require running the container. Deleting the file in a later layer changes nothing, because the value is in the build instruction, not in the filesystem.

BuildKit has a proper answer. A secret mount makes the value available during one RUN and leaves no trace:

FROM alpine:3.20
RUN --mount=type=secret,id=api_token \
    echo "token length: $(wc -c < /run/secrets/api_token)" > /tmp/build.log

$ docker build --secret id=api_token,src=token.txt -t leakdemo:2 .

$ docker history --no-trunc leakdemo:2 --format '{{.CreatedBy}}'
RUN /bin/sh -c echo "token length: $(wc -c < /run/secrets/api_token)" ...
                                   # no value anywhere

$ docker run --rm leakdemo:2 sh -c 'cat /tmp/build.log; ls /run/secrets'
token length: 13                   # it was readable during the build
ls: /run/secrets: No such file or directory      # and is gone now

Runtime secrets are a separate problem with a separate answer: pass them with --env-file or Compose secrets, keep the file out of the image with .dockerignore, and never with ENV.

7.6 The Default Bridge Has No DNS, on Purpose

Section 5.2 showed that ping n1 fails on the default bridge and works on a user-defined network. This surprises people because old tutorials use --link, a deprecated flag that wrote entries into /etc/hosts.

The modern replacement is not a flag, it is a network. Docker runs an embedded DNS server at 127.0.0.11 for every container attached to a user-defined network, and it resolves container names and Compose service names automatically. The default bridge is left without it for backward compatibility with setups built before user-defined networks existed. The practical rule is short: create a network, or use Compose, and never use the default bridge for anything with more than one container.

7.7 A Published Port Can Walk Straight Past Your Firewall

You configured ufw to allow only ports 22, 80 and 443. You start a database container with -p 3306:3306 for a quick test. Your database is now on the internet.

Docker manipulates iptables directly to route published ports to containers, and those rules are evaluated before the ones ufw manages. This is documented behaviour, not a bug, and it catches experienced administrators because everything about it looks correct: ufw status reports exactly the policy you wrote, and the port is open anyway.

Three defences, in order of how much you should prefer them:

• Bind to localhost. -p 127.0.0.1:3306:3306 only ever listens on the loopback interface, so there is nothing for a firewall to block. This is the right answer for almost every case, especially anything behind a reverse proxy.
• Do not publish at all. Containers on the same user-defined network reach each other on the container port directly. A database that only a web container talks to needs no -p line whatsoever.
• Change the daemon's behaviour with "iptables": false in /etc/docker/daemon.json, and take over the routing rules yourself. Powerful, and easy to get wrong. Read Docker's packet filtering documentation before you do.

The habit worth building: after starting anything with -p, run ss -tlnp | grep LISTEN and look at the addresses. 0.0.0.0 means everyone.

7.8 An Image Is Just a Tar File Full of Tar Files

There is no magic in an image format. Save one and look:

$ docker save alpine:3.20 -o alpine.tar
$ tar -tf alpine.tar
blobs/
blobs/sha256/08bc4e534116aa76b16015484b82eac51f9a593416feae9296c8a2d4bb7aa4a2
blobs/sha256/27698c48e88c1988da5594022f53451c70e28738541b64a76b994adf0f357d57
index.json
manifest.json
oci-layout

Each blob is either a compressed tar of one filesystem layer or a small JSON document describing the image. That is the entire OCI image specification in spirit: a manifest, a config, and some tarballs, all addressed by their SHA-256 hash. It is why docker save and docker load can move an image between machines with no registry at all, which is useful on an air-gapped server:

$ docker save myapp:1.0 | gzip > myapp-1.0.tar.gz
$ scp myapp-1.0.tar.gz server:/tmp/
$ ssh server 'gunzip -c /tmp/myapp-1.0.tar.gz | docker load'

It is also why content-addressed pinning works. Every image has a digest, and unlike a tag, a digest cannot move:

$ docker image inspect alpine:3.20 -f '{{json .RepoDigests}}'
["alpine@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc"]

$ docker run alpine@sha256:d9e853e87e55...     # exactly this image, always

7.9 latest Does Not Mean Latest

latest is a tag like any other. It has no special meaning to Docker, it is simply the tag used when you do not name one, and it points at whatever was last pushed with that label. Once it is on your disk, it stays exactly as it was:

$ docker image inspect alpine:latest -f '{{.RepoTags}} {{.Created}}'
[alpine:latest] 2025-02-14T03:28:36Z         # pulled once, long ago

$ docker pull alpine:3.20
3.20: Pulling from library/alpine            # today's 3.20.10

On that machine alpine:latest is over a year older than alpine:3.20, which is not a contradiction once you accept that latest means nothing. Two consequences follow. Never trust latest to be current; run docker pull or docker compose pull deliberately. And never deploy latest, because two servers that pulled at different times are running different software while both report the same tag.

7.10 Knowing Where Docker Stops

Docker is a good tool with clear edges, and part of using it well is recognising the point where something else takes over.

And one honest limit: Docker solves "it works on my machine" for the software, not for the data or the configuration. A container that runs perfectly and points at the wrong database is still an outage.

9. Common Mistakes

9.1 Myth Versus Reality

9.2 Other Traps to Avoid

• Reversing the port mapping. -p 80:8080 when you meant -p 8080:80. Host first, container second, every time.
• Bind-mounting over a directory the build populated. Mounting your project onto /app hides the node_modules or vendor that npm ci or composer install created during the build. Mount a volume over the dependency directory as well, or install at run time.
• Editing files inside a running container. They vanish the next time the container is recreated, and docker compose up recreates containers whenever the configuration changes. Change the image or the mounted source.
• Using docker commit to save your work. It produces an image nobody can rebuild or review. Put the change in the Dockerfile.
• Running a database on a bind mount on macOS or Windows. The filesystem translation layer makes it slow and occasionally unreliable. Use a named volume.
• Forgetting that COPY . . copies your .env. If it is not in .dockerignore, it is in the image, and if you push the image it is public.
• Leaving containers named by Docker. --name costs three seconds and makes every later command, log line and script readable.
• Trusting an image because it has many pulls. Prefer official images and verified publishers, read the Dockerfile if the project publishes it, and scan what you deploy.
• Assuming an image runs on any machine. An amd64 image will not run on an ARM server without emulation. Check with docker image inspect -f '{{.Architecture}}', and build multi-platform images with docker buildx build --platform linux/amd64,linux/arm64.
• Letting the JSON log file grow forever. It lives under /var/lib/docker, so logrotate never sees it, and it will fill the disk on a long-running container.
• Running apt-get upgrade in a Dockerfile. It makes the build non-reproducible and fights with the base image's own update cycle. Pin a newer base image instead.
• Mounting /var/run/docker.sock into a container. That container now has root on the host. Sometimes it is genuinely required, for a CI runner or a reverse proxy that watches for new containers. Treat it as the security decision it is, and mount it read-only where the tool allows.
• Ignoring the build cache when debugging. If a build produces stale results, docker build --no-cache tells you in one run whether the cache was lying to you.
• Storing state in the container filesystem "just for now". Uploads, sessions and SQLite files written outside a volume disappear on the next deployment, and the next deployment is always sooner than you think.