In the previous lesson you built auroralibros/aurora-api:0.1.0 with a Dockerfile that was handed to you ready-made and explained only in passing. It works, it starts the API inside a container and it responds to curl. But you wrote it almost blind: you know what each line does, not why it is written exactly that way. This lesson settles that debt. You are going to go through the Dockerfile language instruction by instruction, at the level of detail left pending in 02-02: why WORKDIR is better than RUN cd, how COPY and ADD differ and why COPY almost always wins, what exactly the two forms of RUN and CMD mean, why chaining commands with && produces smaller images, why EXPOSE does not expose anything, and what happens to your container when you stop it depending on how you wrote the CMD. At the end you will build the definitive aurora-api Dockerfile, commented line by line and with every decision justified.

1. The structure of a Dockerfile, comments and the # syntax directive
2. Summary table of the basic instructions
3. FROM: where you start from
4. WORKDIR: where you work
5. COPY: what you bring in from the context
6. COPY versus ADD
7. RUN: what you execute during the build
8. ENV: configuration that survives the build
9. EXPOSE: documentation, not publishing
10. CMD: which process the container starts
11. The definitive aurora-api Dockerfile

A Dockerfile is a plain text file, with no extension, with one instruction per line:

Syntax rules:

• Instructions are written in UPPERCASE by convention. from node:22-alpine works just the same, but nobody writes it that way: in uppercase you can tell the instruction from its arguments at a glance.
• One instruction per line. To split a long line you use a backslash \ at the end, with nothing after it (not even a space: a space after the backslash reverses its effect and produces baffling errors).
• Lines starting with # are comments, except for the directives in the next section. As you verified in exercise 2 of lesson 02-02, comments do not affect the cache.
• Order matters, and not only because of the cache: each instruction runs on the state left behind by the previous one.
• Blank lines are ignored. Use them to group logical blocks; a well-spaced Dockerfile reads enormously better.

The first line of the file deserves a section of its own:

It is not a comment: it is a frontend directive. It tells BuildKit which version of the Dockerfile frontend to use when interpreting the rest of the file. BuildKit pulls that image from the registry and uses it as the parser.

Why it is worth always including it:

• It gives you the most recent features without updating Docker. docker/dockerfile:1 is a moving tag that points to the latest stable release of the 1.x series. Things like COPY --link, cache mounts or build secrets (lesson 05-05) depend on it.
• It makes the file portable. The same Dockerfile is interpreted identically on your laptop and on a CI agent with another version of Docker.
• It is backward compatible. The 1 series guarantees it will not break existing Dockerfiles.

The variants you will see:

It must be the first line of the file (before any instruction, even before other comments) for it to take effect.

These are the instructions this lesson covers, with the essentials of each one:

The "Creates a layer?" column explains an observation from lesson 01-05: not every instruction fattens the image. COPY, ADD and RUN modify the filesystem and generate layers with real content; the rest only write metadata into the manifest, and their layer weighs zero bytes.

The "When does it act?" column is the one that prevents the most confusion. RUN executes at build time and its result stays frozen; CMD does not execute at build time at all, it only describes what the container will do when it starts. Confusing them is beginners' number one conceptual mistake.

There are more instructions — ARG, ENTRYPOINT, USER, LABEL, HEALTHCHECK, VOLUME, STOPSIGNAL, ONBUILD, SHELL — and they are all covered in the next lesson, 02-04.

FROM is mandatory and must be the first instruction (directives and comments aside). It sets the starting filesystem and metadata: everything that comes after is built on top of those layers.

Full syntax:

Forms you will see, applied to Aurora Libros:

The trade-off between reproducibility and maintenance is real and has no single answer:

Aurora Libros uses node:22-alpine, decided in lesson 01-07 for three reasons you can now fully justify: it satisfies the engines: node >=22.0.0 in package.json, it is an official image (the library/ namespace, the first trust criterion from lesson 02-01) and it weighs ~142 MB against the ~1.1 GB of node:22. The trade-off is that Alpine uses musl instead of glibc as its C library; the project's three dependencies (express, pg, redis) are pure JavaScript or ship compatible binaries, so it is not a problem.

The AS <name> clause names a build stage. It is used for multi-stage builds, the technique that lets you compile in one image and carry only the result over to a much smaller one. It is studied in lesson 05-04; make a mental note and move on.

WORKDIR sets the working directory for all subsequent instructions that use one: RUN, COPY, ADD and CMD. If it does not exist, it creates it, including intermediate directories.

It is the inevitable question. Compare:

In the first case, npm ci runs in /, not in /app, and fails with ENOENT: no such file or directory, open '/package.json'. The reason is fundamental: every RUN executes in a fresh temporary container. The cd changes the shell's directory in that ephemeral container, which dies as soon as the instruction ends; the next RUN starts from scratch, in the working directory inherited from the image.

The only way for cd to be useful is to chain it inside the same RUN:

Even so, WORKDIR wins for four reasons:

1. It persists at runtime. It is the directory you land in with docker exec -it aurora-api sh and where the CMD runs. A cd inside a RUN leaves no trace.
2. It creates the directory if it does not exist, with no need for mkdir -p.
3. It is visible metadata. docker image inspect tells you what it is; a cd buried in a RUN has to be hunted down.
4. It reads better. It declares the intent instead of hiding it inside a chain of commands.

Additional details:

Always use absolute paths. Chained relative ones force you to keep mental track of where you are and are a classic source of errors in long Dockerfiles.

For Aurora Libros, /app is the usual convention in Node images. Any path would do (/srv/aurora, /usr/src/app), but /app is short, unambiguous and does not collide with Alpine's filesystem.

COPY brings files and directories from the build context into the image's filesystem.

Rules you need to be clear about:

• The source is always relative to the root of the context, never to your current directory nor to the Dockerfile's location. And it can never leave the context: that is the restriction that caused the "/db/init.sql": not found error in lesson 02-02.
• The destination is relative to the WORKDIR if it is not absolute. With WORKDIR /app, the destination ./ means /app/.
• If the destination ends in /, it is treated as a directory; if it does not, and there is a single source, it is interpreted as the name of the destination file. Always adding the trailing slash avoids surprises.
• With several sources, the destination must be a directory and end in /.
• COPY copies the contents of a directory, not the directory itself. COPY web/ /public/ leaves the contents of web/ directly in /public/, not in /public/web/. It is the number one source of paths that "do not show up" inside the image.

Examples with Aurora Libros:

About COPY package*.json ./: the wildcard covers package.json and package-lock.json in one go. It has a practical advantage over naming them separately: it does not fail if package-lock.json does not exist, because the pattern simply matches fewer files. COPY package.json package-lock.json ./, on the other hand, errors out if the lock is missing. Both forms are defensible: the explicit one catches a forgotten lock earlier (which would break the npm ci), the wildcard one is more forgiving. Aurora Libros will use the wildcard, which is the most widespread convention in the Node ecosystem.

By default, everything copied belongs to root:root. --chown changes the owner in the same operation:

The node:22-alpine image already includes an unprivileged node user. Copying directly with its ownership avoids a subsequent RUN chown -R node:node /app, which would double the size of that layer: changing a file's permissions marks it as modified and the copy-on-write from lesson 01-05 forces a full copy to be written into the new layer. A recursive chown over node_modules can add tens of megabytes to the image.

--chmod does the same for permissions:

Using USER to run the container without privileges is covered in lesson 02-04, and the reasoning in depth in 05-03.

ADD has existed since Docker's very first day and does everything COPY does, plus two extra things. That is precisely why it is worth avoiding.

The problem with ADD is that its behavior depends on what you pass it:

Three different behaviors from the same instruction. Whoever reads the Dockerfile has to know by heart which formats get extracted in order to predict the result. COPY always does exactly the same thing: copy.

And the URL case is worse:

Four cumulative problems: the .tar.gz stays forever in the ADD's layer even if you delete it afterwards (copy-on-write, lesson 01-05), you cannot verify the checksum before using it, ADD does not extract what comes from a URL (only local files), and you have no control over headers or authentication. The correct form, all in a single RUN:

Here you do verify the hash, and the deletion happens within the same layer, so the temporary file does not fatten the image.

The practical rule: always use COPY. The only case where ADD genuinely contributes something is extracting a local tarball from the context, which saves you having tar in the image:

There is no ADD at all in the aurora-api Dockerfile: there are no tarballs and no downloads.

RUN executes a command at image build time, inside a temporary container based on the previous layers, and freezes the resulting filesystem into a new layer. It is the instruction that installs packages, compiles, generates files… and the one that adds the most weight.

For RUN, the shell form is the usual one, because you almost always want to chain commands or expand variables. The exec form is only needed in images with no shell (scratch, distroless) or when an argument contains characters the shell would misinterpret.

Watch out for the quotes: the exec form is JSON, so it requires double quotes. RUN ['npm', 'ci'] with single quotes is not valid JSON and BuildKit will treat it as the shell form, with baffling results.

This is the part that really matters. Every RUN creates a layer. Compare:

Two problems with the bad version, and the second is the serious one:

1. Four layers where one was enough. More metadata, more manifest entries, more slowness when mounting the image.
2. The rm -rf at the end frees nothing. Remember from lesson 01-05: layers are diffs and they only stack. Deleting a file in layer 4 does not remove it from layer 2; it only writes a deletion marker that hides it. The file still travels inside the image, taking up its space on every download.

Check it for yourself:

48 MB of difference for moving an rm from one line to another. The deleted file "exists" all the same inside the bad image, invisible but downloadable.

Hence the three golden rules of RUN:

1. Group related operations into a single RUN with && and \.
2. Clean up in the same layer where you make the mess. Package manager caches, temporary files, source code you have already compiled.
3. But do not group everything. If you cram dependency installation and application startup into a single RUN, you lose cache granularity. The balance: one RUN per purpose.

A warning about Debian: apt-get update and apt-get install must always go in the same RUN. If you separate them, the cache may reuse an update from weeks ago while running a fresh install, and you will end up installing versions that are no longer in the repositories. It is the classic mistake known as apt cache busting.

Broken down:

• npm ci instead of npm install. ci stands for clean install: it deletes node_modules if it exists and installs exactly the versions pinned in package-lock.json, with no range resolution. If the lock and the package.json do not agree, it fails instead of improvising. That is exactly what you want in an image: two builds of the same commit produce the same bytes. npm install, by contrast, may resolve ^4.21.2 to 4.21.2 today and to 4.22.0 next month, producing different images from the same code.
• --omit=dev excludes the devDependencies. Aurora Libros has none today, but as soon as linters or test frameworks come in, this option will stop them travelling to production. It replaces the old --production, now discouraged.
• npm cache clean --force deletes the cache npm leaves in ~/.npm, which can be around 50 MB. It goes in the same RUN for everything explained above: in a separate RUN it would not save a single byte.

ENV defines environment variables that exist for the rest of the build and also inside the running container. That double life is its distinguishing feature, and it is what sets it apart from ARG (lesson 02-04).

Syntax:

Always use the form with =. The old one is ambiguous with values containing spaces and is deprecated.

The variables you define can be used in later instructions:

And they persist at runtime. Check it with the image you already have:

The important thing is that they are overridable default values when the container starts:

That -e takes priority over the image's ENV. It is exactly the mechanism that lets the server.js from lesson 01-07 — which reads all its configuration from process.env — work unchanged on your laptop and in production.

The last row is the rule you have been carrying since lesson 01-07 and that you can now demonstrate. If somebody wrote ENV DB_PASSWORD=superSecret2026, anyone with access to the image would see it:

There it all is, in the clear, without even having to start the container. And by publishing the image to the public auroralibros/aurora-api repository, on the internet.

NODE_ENV=production deserves a comment because in Node it is not decorative: Express disables debug views and caches templates, many libraries reduce their logging and npm install would skip the devDependencies. It is a real behavior change, not a label.

Here is the trap that catches everybody. Reading "expose", anyone understands "open this port to the outside world". EXPOSE opens nothing, publishes nothing and changes no networking behavior. It is exclusively documentation in the form of metadata.

What it does do:

• It records in the image's metadata which port the service uses, so that whoever runs it knows without reading the code.
• It shows up in docker image inspect and in the PORTS column of docker ps.
• It enables the docker run -P option (uppercase), which publishes all the ports declared with EXPOSE on random high ports of the host.
• Docker Compose and some orchestrators read it as a hint.

What it does not do: publish the port. That is still the exclusive job of -p in docker run, as you learned in lesson 01-06.

Prove it. Your 0.1.0 image has EXPOSE 3000. Start it without -p:

Look at the PORTS column: it says 3000/tcp, with no -> arrow at all. That means "the container declares this port", not "it is published". Check it:

Now with uppercase -P, which does publish what is declared:

Now there is an arrow: the container's port 3000 is published on the host's port 32768, chosen at random. Clean up:

So why bother writing EXPOSE at all? For three solid reasons:

1. It documents the image's interface. Whoever receives it knows which port to map without reading server.js.
2. It is the contract with the orchestrator. Compose (module 4), Swarm and Kubernetes (module 6) use it as a reference.
3. It costs nothing. It is metadata: it does not add a single byte to the image.

Full syntax:

CMD defines the default command that runs when a container is started from the image. It does not run during the build: it is only stored as metadata.

And there is a rule that governs everything else, already seen in lesson 01-06: a container lives as long as its main process lives. When the CMD's process ends, the container stops. That is why CMD ["node", "server.js"] keeps the container alive (the server does not end) and CMD ["echo", "hello"] produces a container that dies instantly.

They look equivalent, and under normal conditions they are. The difference shows up when you stop the container, and it is important enough to look at in detail.

With the exec form, Docker runs node server.js directly. The node process is PID 1 inside the container.

With the shell form, Docker runs /bin/sh -c "node server.js". PID 1 is sh, and node is a child process:

When you run docker stop, Docker sends SIGTERM to PID 1 and waits 10 seconds before sending SIGKILL. With the exec form, node receives the SIGTERM and can close connections, flush buffers and exit. With the shell form, the SIGTERM goes to sh, which does not forward it to its children: node never finds out, keeps working, and after 10 seconds a SIGKILL kills it with no chance of cleanup. Requests cut off halfway through and half-finished transactions.

Measure it:

0.3 seconds versus 10.2. Ten seconds of difference over a pair of brackets, multiplied by every container in every deployment. In a rolling deployment with twenty replicas (module 6), that difference is what separates a clean rollout from one with errors for your users.

Clean up:

Rule: always use the exec form, with brackets and double quotes. It is JSON: single quotes will not do.

• Only the last one counts. If you write several CMDs, the earlier ones are discarded silently.
• It is overridden from the command line. Anything you put after the image name replaces the CMD:

It did not start the server: you replaced the CMD with node --version. This flexibility is useful for debugging (docker run --rm -it yourimage sh gives you a shell inside the image) and it is the basis of the ENTRYPOINT + CMD pattern from lesson 02-04.

• If the base image has an ENTRYPOINT, the CMD becomes its arguments. That is precisely the subject of 02-04.
• Do not use CMD for several processes. CMD ["sh", "-c", "node server.js & nginx"] is an antipattern: one container, one process. Aurora Libros has four services because it will have four containers.

You can now justify every line. This is the module's final Dockerfile, which replaces the minimal one from lesson 02-02. Save it as ~/aurora-libros/api/Dockerfile:

Build version 1.0.0, which is the one matching the version in package.json:

Change the code and rebuild, which is what you will do fifty times a day:

1.2 seconds, with the npm ci untouched in the cache. The order of the instructions — dependencies at the top, code at the bottom — does exactly what it was designed to do.

Verify the finished image:

Every piece of metadata you have been declaring is there, readable. And no credentials among them, as the project's rule demands. One final functional check:

Just like in 02-02: the service is alive and responding; the dependencies still do not exist, and that is module 3.

• RUN cd /app expecting it to persist. Every RUN runs in a different temporary container. Use WORKDIR.
• CMD in shell form. Ten extra seconds on every stop and signals that never reach your process. Always use CMD ["executable", "arg"] with double quotes: it is JSON, not Python.
• Believing that EXPOSE publishes the port. It publishes nothing. EXPOSE documents; -p publishes. If your service "does not respond" and you cannot see the -> arrow in the PORTS column of docker ps, that is the problem.
• Cleaning up in a different RUN from the one that made the mess. The deletion frees nothing: the lower layer keeps the files. Chain with && in the same instruction.
• apt-get update and apt-get install in separate RUNs. The cache reuses a stale index and the install either fails or installs obsolete versions. Always together.
• npm install instead of npm ci. It breaks reproducibility: the same commit can produce different images. And do not forget --omit=dev.
• ADD out of habit. Its behavior depends on the file type and it hides unverified remote downloads. Use COPY unless you need to extract a local tarball.
• Secrets in ENV. They stay in the metadata, visible with docker image inspect without even starting the container, and they travel with the image wherever it goes. Never.
• COPY . . without a .dockerignore. You already saw it in 02-02: bloated context, broken cache and the risk of leaking a .env.
• Tip: comment the why, not the what. # Installs dependencies is redundant: you can see that. # The cache clean goes here so it actually frees space is what whoever reads it six months from now will thank you for.
• Tip: read other people's Dockerfiles. Those of the official images are on GitHub (lesson 02-01) and they are an excellent school.

Build two images based on node:22-alpine that install the git package with apk:

• Version A: apk add git in one RUN and rm -rf /var/cache/apk/* in a later RUN.
• Version B: everything chained with && in a single RUN, using apk add --no-cache.

Compare the sizes with docker image ls and use docker image history to locate the layer responsible for the difference. Explain the result in terms of layers and copy-on-write.

1. Write two Dockerfiles that are identical except for the CMD: one in exec form and one in shell form, both starting node server.js from the Aurora Libros image.
2. Start a container from each.
3. With docker exec <container> ps -o pid,comm, check which process is PID 1 in each case.
4. Time docker stop on both with time.
5. Explain why the difference is exactly about 10 seconds and not some arbitrary value, and which docker stop option would let you change that wait.

This Dockerfile for the Aurora Libros API has seven problems related to what you have seen. Identify them, explain the consequence of each one and write the corrected version.

Solution to exercise 1

Four megabytes of difference (with larger packages, the difference reaches tens or hundreds). Locate the guilty layer:

The reading is conclusive: the rm -rf layer weighs 0 B. It has freed nothing. It has only written deletion markers (whiteouts) that hide the files in the lower layer, but that 19.2 MB layer is still in the image and gets downloaded in full on every docker pull.

In version B, --no-cache means apk never writes the index to disk, so there is nothing to delete. It is a direct application of the copy-on-write from lesson 01-05: a layer can only add content or hide it, never shrink the previous layers. Hence the rule: make the mess and clean it in the same instruction.

Solution to exercise 2

3. The processes:

Confirmed: in the exec form node is PID 1; in the shell form PID 1 is sh and node is its child with PID 7.

4. The timings:

5. The difference is exactly ~10 seconds because that is the value of docker stop's grace timer: it sends SIGTERM to PID 1, waits 10 seconds and, if the container is still alive, sends SIGKILL.

• In the exec form, node receives the SIGTERM. Even though this server.js installs no explicit handler, Node's default behavior on SIGTERM is to exit immediately: 0.3 s.
• In the shell form, sh receives the SIGTERM and does not forward it to its children (a minimal POSIX shell does no signal forwarding). node never finds out. The 10 seconds run out and the SIGKILL arrives, which the process cannot catch: an abrupt shutdown, severed connections, no chance to flush buffers or close the PostgreSQL pool.

The timeout can be adjusted with docker stop -t <seconds>:

Lowering the timeout solves nothing: the process still does not receive the signal. The solution is the exec form, or an ENTRYPOINT with a script that uses exec "$@" (lesson 02-04). Cleanup:

Solution to exercise 3

The seven problems:

An eighth, minor detail: ENV NODE_ENV production uses the old syntax without =, discouraged for being ambiguous.

Corrected version:

The password is injected at runtime, never at build time:

And in module 4 it will not even be on the command line, but in a .env file outside version control (lesson 04-05) or in a managed secret (lesson 05-03).

You have now mastered the Dockerfile language. You know that the # syntax=docker/dockerfile:1 directive gives you the most recent frontend without updating Docker, and that of the eight basic instructions only COPY, ADD and RUN fatten the image: the rest write metadata that weighs nothing. FROM sets the starting point and the trade-off between reproducibility and automatic patches. WORKDIR replaces a RUN cd that would never work, because every RUN lives in a different temporary container, and it also persists at runtime. COPY resolves its paths against the context and copies the contents of directories; ADD adds extraction and downloads with a variable behavior that makes it the worse option except for local tarballs.

With RUN you have seen the most profitable rule of all: clean up in the same layer where you make the mess, because a layer can only add or hide, never slim down the previous ones — 48 MB of difference in the demonstration with python3. With ENV you have told a legitimate default value (NODE_ENV, PORT) apart from what must never go into an image (DB_PASSWORD), and you have verified it by reading the metadata with docker image inspect. With EXPOSE you have dismantled the trap in the name: it documents, it does not publish, and the proof is the missing -> arrow in docker ps. And with CMD you have measured first-hand that the exec form and the shell form are not alternative styles: they are 0.3 seconds versus 10.2 when stopping the container, because PID 1 is either node or sh, and sh does not forward SIGTERM.

The result is auroralibros/aurora-api:1.0.0: 167 MB, commented line by line, with every decision justified, rebuilding in 1.2 seconds after a code change and without a single secret inside. It is a Dockerfile that works.

In the next lesson, Advanced Dockerfile Instructions, you will turn it into a professional one. You will learn to parameterize the base version with ARG and how it differs from ENV, to separate the fixed executable from its arguments by combining ENTRYPOINT and CMD, to stop running the API as root with USER, to describe the image with OCI labels through LABEL, and to have Docker watch the /health endpoint on its own with HEALTHCHECK so that docker ps shows healthy or unhealthy. That is the leap between an image that starts and an image you can put into production without blushing.