Dockerfile — an image recipe and docker build

A Dockerfile is a text file that docker build turns into an image. Every line is an instruction: take a base, copy files, run a command, set the start command. Instructions run top to bottom, and each one that changes files produces a layer.

student@ubuntu:~/app$ sudo docker build -t app:1.1 .
#0 building with "default" instance using docker driver
…
#4 [1/4] FROM docker.io/library/busybox:latest@sha256:27be924c62a0…
#4 DONE 0.1s
#5 [internal] load build context
#5 transferring context: 31B done
#6 [2/4] WORKDIR /www
#6 DONE 0.1s
#7 [3/4] COPY index.html .
#7 DONE 0.1s
…
#9 naming to docker.io/library/app:1.1 done

-t app:1.1 gives the image a name and a tag; the dot at the end is the directory to take files from. The build lines are numbered #1, #2…: first the service steps [internal], then the instructions in order — [2/4] means the second of four. The last line of a step tells how it ended: DONE with the time, or CACHED. CMD, EXPOSE and ENV get no steps of their own: they record image settings.

On the lab machine BuildKit runs the build (the buildx component, the docker-buildx package).

Instructions

FROM comes first. Docker looks for the base among the images on the machine and goes to a registry if it is missing. The lab machine has no network, so FROM can only use loaded images: alpine, nginx:alpine, busybox.

RUN runs at build time, CMD every time a container starts. RUN apk add … fails without network: that command fetches packages from the internet.

EXPOSE opens nothing: docker run -p publishes a host port (Ports). An ENV from the image can be overridden at run time: docker run -e MODE=dev. VOLUME /data in the image means every docker run without -v mounts a new empty volume at /data — see Volumes.

Build context

The build context is the directory docker build sends to the Docker service in full: the last argument, usually a dot. The [internal] load build context step says how much was sent: transferring context: 31B done.

COPY takes files only from the context. A COPY path starts at its root and cannot go above it: COPY ../secret.txt . looks for /secret.txt inside the context and fails:

ERROR: failed to build: failed to solve: failed to compute cache key:
failed to calculate checksum of ref …: "/secret.txt": not found

If the file you need is outside, copy it into the build directory or build from the directory above: docker build -f app/Dockerfile ..

.dockerignore next to the Dockerfile keeps things out of the context — one pattern per line:

*.log
.env
.git

That keeps logs and secrets out of the image and stops the build from shipping gigabytes when the directory holds data.

Build cache

A rebuild with no changes redoes nothing: every step comes from the build cache.

#6 [2/4] WORKDIR /www
#6 CACHED
#7 [3/4] COPY index.html .
#7 CACHED

A step comes from the cache if the instruction, the layer below it and — for COPY — the content of the copied files are unchanged. Change one step and it and every step below are rebuilt. After editing index.html only WORKDIR comes from the cache; COPY and the steps below it run again.

Hence the ordering rule: what rarely changes (base, user, dependency install) goes up; application files you edit often go down. --no-cache rebuilds everything.

The cache compares RUN by the command text only. RUN date > /built keeps the date of the first build in the cache.

CMD and ENTRYPOINT

CMD comes in two forms:

In exec form every word is a separate quoted string. One string for the whole command — CMD ["httpd -f -p 80"] — means "run the program named httpd -f -p 80". The build passes, the container does not start: exec: "httpd -f -p 80": executable file not found in $PATH.

In shell form the main process is a shell, and variables in the line are expanded. Busybox sh with a single command replaces itself with it: docker top shows only httpd.

Words after the image name in docker run replace CMD entirely: docker run --rm app:1.1 ls /www. If the image has an ENTRYPOINT, those words are appended to it:

student@ubuntu:~$ cat Dockerfile.ep
FROM busybox
ENTRYPOINT ["echo", "hello"]
CMD ["world"]
student@ubuntu:~$ sudo docker run --rm ep:1
hello world
student@ubuntu:~$ sudo docker run --rm ep:1 student
hello student

The main process must run in the foreground: the container lives as long as it does (Main process). httpd without -f goes to the background, and the container exits at once with Exited (0).

• container-images — layers, tags, digests and what docker load does.
• docker — running a container from the image: ports, volumes, restarts.
• docker-compose — building and running several services from one file.
• env-vars — environment variables and ENV.
• users-groups — users and UIDs for USER.
• exit-codes — what codes 0, 1, 127 and 137 mean.