The Dockerfile you closed the previous lesson with works: it builds auroralibros/aurora-api:1.0.0, starts Express in a container and responds to curl. But it is missing the pieces that separate an image that works from an image you can put into production without blushing. Right now the API runs as root inside the container, nobody knows who built it or from which commit, Docker has no way of knowing whether the process is alive but stuck, the Node version is hardcoded into the FROM, and you cannot run the image with a different command without losing its default behavior entirely. This lesson solves all five things. You are going to learn ARG and its critical difference from ENV, the ENTRYPOINT + CMD pairing with its four combinations, USER to stop being root, LABEL with the OCI standard, HEALTHCHECK against the /health endpoint you prepared in lesson 01-07, and the minor instructions — VOLUME, STOPSIGNAL, ONBUILD and SHELL — that are worth knowing even if you rarely use them. At the end you will have the professional aurora-api Dockerfile.

1. ARG versus ENV: scope and timing
2. ARG before the first FROM
3. ENTRYPOINT versus CMD: the four combinations
4. The docker-entrypoint.sh pattern and why exec "$@" matters
5. USER: stop running as root
6. LABEL and the standard OCI labels
7. HEALTHCHECK: let Docker watch your service
8. VOLUME and why declaring it is usually a bad idea
9. STOPSIGNAL and signal handling
10. ONBUILD and SHELL
11. The professional aurora-api Dockerfile

Both define variables. The confusion between them is constant, and the difference is easy to state: ARG exists only during the build; ENV also exists inside the running container.

An example that demonstrates everything. Create /tmp/arg-env/Dockerfile:

During the build, both are available. Now run it:

The ARG is empty. It is not that it holds something else: it does not exist. It evaporated when the build finished. The ENV is still there.

And this is how you pass a value in from outside:

The most useful pattern is combining them: an ARG that feeds an ENV.

That way, --build-arg BUILD_VERSION=1.2.3 at build time ends up as an environment variable you can query inside the container. It is how version numbers and commit hashes are injected from a CI pipeline (lesson 06-02).

This one has to be burned in:

There is the password, in the clear, in the image's history. Anyone who pulls the image can read it with a single command, without starting anything. And by publishing to the public auroralibros/aurora-api repository, on the internet.

It is the same rule you have been carrying since lesson 01-07, now with an additional leak path: it is not only ENV that leaks secrets, ARG does too. To pass credentials into a build safely there are BuildKit secret mounts (RUN --mount=type=secret), which leave no trace in any layer; they are studied in lesson 05-05. For Aurora Libros the rule stays intact: credentials do not go into the image, neither at build time nor at runtime; they are injected when the container starts.

ARG has a scoping quirk that surprises everybody: an ARG declared before the first FROM is only visible in the FROM lines, not inside the image.

That double declaration (ARG NODE_VERSION with no value, inside the stage) is how you "re-import" the global argument. Without it, the variable would be empty inside the RUN.

The practical usefulness is enormous: parameterizing the base version without touching the Dockerfile.

Real use cases for Aurora Libros:

A warning: parameterizing the base is convenient, but the default value must be the production one. If the ARG has no default value and somebody builds without --build-arg, they will get node:-alpine, which does not exist, and a cryptic manifest error.

CMD, which you already know, defines what runs when the container starts and is discarded entirely if you pass a command to docker run. ENTRYPOINT defines an executable that is not discarded: the docker run arguments are appended after it.

Combining the two produces four scenarios. This table is the reference worth keeping to hand:

The rule that sums up all four rows: ENTRYPOINT is the fixed executable; CMD is the default arguments, and it is the only thing the user can replace.

Check it with the image you already have:

The CMD ["node","server.js"] has vanished: the server does not start.

Here --version has replaced server.js, but node is still there: node --version was executed. The executable is untouchable.

Advantages over CMD alone:

• The image has a clear identity. It is "the image that runs node", not "a generic image".
• It is self-documenting. docker run yourimage --help just works.
• It prevents accidents. Nobody carelessly starts a container that does not do what the image promises.

And its main drawback: debugging is harder. With CMD alone, a docker run --rm -it yourimage sh gives you a shell. With ENTRYPOINT ["node"], that command tries to run node sh and fails. That is what --entrypoint is for:

--entrypoint replaces the fixed executable. Watch out for one confusing detail: --entrypoint accepts a single value, and everything after the image name is passed to it as arguments:

Everything you learned in lesson 02-03 about CMD applies equally to ENTRYPOINT, only worse:

With ENTRYPOINT in shell form two bad things happen, not one:

1. PID 1 is sh and it does not forward SIGTERM: the 10 seconds of waiting and the SIGKILL from the previous lesson.
2. CMD is ignored entirely, and so are the docker run arguments. An ENTRYPOINT in shell form swallows the whole argument mechanism.

With ENTRYPOINT, the exec form is not a recommendation: it is mandatory.

When startup needs logic — waiting for a dependency, generating a configuration file, applying migrations — the ENTRYPOINT points at a script.

Create ~/aurora-libros/api/docker-entrypoint.sh:

And the Dockerfile brings it in like this:

The complete flow:

This is the part you really have to understand.

• "$@" is all the arguments received, each one quoted separately. Since the ENTRYPOINT is the script and the CMD is ["node","server.js"], "$@" is node server.js. The quotes are essential: without them, an argument containing spaces would be split in two.
• exec is the crucial part. Without exec, the shell spawns a child and waits: PID 1 is still the script, and you are in exactly the shell-form scenario from lesson 02-03 — SIGTERM to the script, which does not forward it, ten seconds and SIGKILL. With exec, the shell replaces itself with node: same PID, same file descriptors, the script disappears from the process tree and node becomes PID 1.

Check it with the script in place:

PID 1 is node, not sh. The script ran, did its job and stepped aside. And therefore:

If you removed the exec, that figure would be 10 seconds. One difference of four letters, and the container's entire shutdown behavior changes.

A practical note: the script uses nc (netcat), which is not installed in node:22-alpine. You would have to add RUN apk add --no-cache netcat-openbsd. The final version in this lesson chooses not to include the active wait, because Docker Compose solves startup dependencies more cleanly with depends_on and health conditions (lesson 04-02). The pattern is still worth knowing, though: you will run into it in the official PostgreSQL and MySQL images, which use it exactly this way.

Right now your API runs as root inside the container. Check it:

uid=0 is root. A container is isolated, but that isolation is not an impenetrable wall: if a runtime escape vulnerability appears or you mount a volume badly, root in the container can become root on the host. Running as an unprivileged user eliminates that whole class of problems for the cost of three lines.

The instruction is USER, and it affects all subsequent Dockerfile instructions and the container's process:

node:22-alpine already ships a node user (uid 1000), so USER node would be enough. But it is worth knowing how to create one, because other bases do not have it:

The options of Alpine's tools (BusyBox), which differ from Debian's:

On Debian/Ubuntu the equivalent would be groupadd -g 1001 aurora && useradd -u 1001 -g aurora -m -s /bin/sh aurora.

This is the point where everybody trips up:

The correct sequence is: install and copy as root (which can write wherever it likes), assign ownership in the same copy operation with --chown, and put USER right before the CMD. As you saw in 02-03, --chown in the COPY avoids a subsequent RUN chown -R that would double the layer's size because of copy-on-write.

Check the result on the final image:

An unprivileged user cannot listen on ports below 1024. If your application used port 80, it would stop starting:

That is why aurora-api listens on 3000, and why the Nginx container in module 4 will need care. The solution is never to go back to root: it is to listen on a high port and publish it wherever needed with -p 80:3000, since the mapping is done by Docker on the host, not by the process.

The complete hardening of runtime security — capabilities, --read-only, no-new-privileges, seccomp profiles, user namespaces — is lesson 05-03. Here you take away the essential point: a production container does not run as root.

LABEL adds arbitrary metadata to the image as key-value pairs. It does not change behavior, it weighs nothing, and it answers questions that become urgent in production: which commit did this image come from? who maintains it? what version is it?

Always group several labels into a single instruction: each LABEL creates a metadata layer.

So that tools can read this data there is a standard vocabulary, org.opencontainers.image.*, defined by the Open Container Initiative (the same one from lesson 01-03):

Applied to Aurora Libros, combining ARG for whatever varies on each build:

The first three ARGs are filled in at build time, typically from the pipeline:

And this is how you read them back afterwards:

The real value of this becomes obvious at three in the morning on a Tuesday: production is failing, you have a container running and you need to know exactly what code is inside it. A docker inspect gives you commit 7a3f912, and with it git log tells you the whole story. Without that label, the archaeology begins.

Labels are also useful for filtering, with the syntax from lesson 01-04:

A container can be Up and completely useless: the process is alive but the event loop is blocked, the connection pool is exhausted or the application is returning 500 to everything. docker ps would happily say Up 3 hours. HEALTHCHECK gives Docker a way to check its real health.

The command determines the state by its exit code: 0 = healthy, 1 = unhealthy. Any other value is treated as an error.

--start-period deserves special attention. Without it, an application that takes 20 seconds to start would be marked unhealthy during that legitimate startup, and in an orchestrator it would be killed and restarted in an endless loop. The grace period says: "during the first N seconds, if it fails, do not count it".

Aurora Libros has had the /health endpoint since lesson 01-07, designed precisely for this: it returns 200 if the database and the cache respond, and 503 if not.

The details behind the choice of command:

• wget and not curl: node:22-alpine ships wget (from BusyBox) but not curl. Using curl would force an apk add curl that adds around 4 MB. If you prefer curl, the option is curl -f http://localhost:3000/health || exit 1, where -f makes it return an error code on an HTTP 4xx/5xx.
• --spider: it does not download the body, it only checks that the resource responds.
• --tries=1: no internal retries; Docker already retries with --retries.
• || exit 1: normalizes any failure to exit code 1, which is what Docker expects.
• localhost: the check runs inside the container, so localhost is the service itself. It needs no published ports.
• The timings: every 30 s, with 3 s of patience, 10 s of grace at startup and 3 consecutive failures before declaring it unhealthy. In the worst case, a downed service is detected in about 90 seconds.

Just after starting:

health: starting is the grace period. Wait and look again:

unhealthy, and rightly so: /health returns 503 because there is no PostgreSQL and no Redis, exactly as in the previous lessons. The healthcheck is doing its job with complete precision: the process is alive, but the service is not operational. Precisely the distinction that Up cannot make.

The full history is in the metadata:

FailingStreak: 3 is the three consecutive failures that triggered the state change. The Log field keeps the most recent checks with their output, which is where you look when a healthcheck fails and you do not know why.

The possible states:

And why it matters beyond the docker ps column:

• Docker Compose can wait for a service to be healthy before starting another with depends_on: condition: service_healthy (lesson 04-02). It is the clean solution to the problem the script in section 4 was trying to solve by hand.
• Docker Swarm automatically replaces unhealthy replicas (lesson 06-03).
• Kubernetes has its own equivalent mechanism, probes (lesson 06-05).

Clean up:

If your base image defines a healthcheck that is no use to you, you can disable it:

It is rare, but it comes up when you inherit from corporate images with checks that do not apply to your case.

VOLUME declares that a directory in the image should be mounted as a volume:

When you start a container from that image without specifying anything, Docker will automatically create an anonymous volume for that path.

It sounds useful, and yet the general recommendation is not to use it. Four reasons:

1. It generates orphaned anonymous volumes. Every docker run without an explicit -v creates a volume with a random name that is not deleted when you remove the container (unless you use docker rm -v). On a development machine you accumulate tens of gigabytes of volumes with names like f3a9c2e1b8... that nobody knows whether they matter. You will see them in docker system df in lesson 02-05.
2. It cannot be undone. Once an image declares VOLUME /data, whoever uses it cannot remove it. It imposes a storage decision on them that may not suit them.
3. It breaks any later COPY. Anything you write to that path after the VOLUME in the Dockerfile is silently lost, with no warning at all. It is a maddening error to diagnose.
4. It is a runtime decision, not an image decision. Who mounts what and where is decided by whoever deploys, with -v or with Compose's volumes: section.

A demonstration of point 3:

The file is not there. It was written into a layer that the volume mount covers up.

No Dockerfile in Aurora Libros uses VOLUME. The API keeps no state — it reads from PostgreSQL and caches in Redis — and the catalog's persistence is handled by mounting a volume at runtime on the aurora-db container, which is the subject of lesson 03-06. Interestingly, the official PostgreSQL image itself does declare VOLUME /var/lib/postgresql/data, and that is exactly why orphaned anonymous volumes show up as soon as you experiment with it without -v.

STOPSIGNAL changes the signal Docker sends to PID 1 when you run docker stop:

You already know the default behavior from lesson 02-03: docker stop sends SIGTERM, waits 10 seconds and sends SIGKILL, which can neither be caught nor ignored.

The problem is that not every program interprets SIGTERM the same way:

The Nginx case is the one that affects Aurora Libros: the aurora-web container in module 4 will want STOPSIGNAL SIGQUIT so it does not cut off half-served requests during a deployment.

For the API, SIGTERM (the default) is correct, but it is worth having server.js catch it in order to shut down cleanly. The pattern, which will be picked up again in lesson 06-01:

Notice the 8-second timer: it is deliberately lower than the 10 of docker stop, to force an exit before the SIGKILL arrives. And remember that none of this is any use if the CMD is in shell form: the signal would never reach the Node process.

Two instructions of minority use that are worth recognizing.

It registers an instruction that does not run now, but when somebody uses this image as a base with a FROM.

Whoever uses it only writes:

And at build time, the three registered steps fire automatically. It is a template for standardizing an organization's microservices.

Why it is rarely used: the hidden magic. Whoever reads that one-line Dockerfile cannot see what is going to happen; they have to go and inspect the base. Debugging a failure in an ONBUILD is especially frustrating, because the error points at a file that does not contain the guilty instruction. The official Node images themselves retired their onbuild variants years ago for this very reason. If you need standardization, today a shared Dockerfile template or a well-documented base file is preferable.

It changes the interpreter used by the shell form of RUN, CMD and ENTRYPOINT:

The default on Linux is ["/bin/sh", "-c"]. The most common and legitimate use case on Linux is enabling bash's strict mode in images with many chained RUNs:

Without pipefail, that RUN succeeds even if the curl fails, because a pipeline's exit code is that of the last command, and grep would still run. With pipefail, a failure in any link makes the whole instruction fail. It is a classic silent failure that produces images with empty files.

A note for Alpine: node:22-alpine does not ship bash, only BusyBox's ash. Using SHELL ["/bin/bash", …] there would require RUN apk add --no-cache bash. There is no SHELL at all in the aurora-api Dockerfile: there are no pipelines in its RUNs.

Everything together. Save this as ~/aurora-libros/api/Dockerfile:

Build the new version:

A full verification of everything you have added:

Notice the detail: with ENTRYPOINT ["node"], the argument --eval "..." replaced the CMD ["server.js"] and node --eval ... was executed. Case 3 from the table in section 3, live.

All three things confirmed: the grace period, the correct detection that the service is not operational (PostgreSQL is missing, module 3) and a stop in 0.3 seconds thanks to the exec form.

Compare with the previous version:

All of that improvement has cost zero bytes.

• Using ARG for secrets. They stay in docker image history in the clear. For build-time credentials there are BuildKit secrets (lesson 05-05); for runtime credentials, -e and environment files (lesson 04-05).
• Expecting a global ARG to be available inside the stage. ARGs before the first FROM are only visible to the FROMs. They have to be declared again, with no value, inside the stage.
• ENTRYPOINT in shell form. It breaks two things: PID 1 becomes sh (a 10 s stop) and the docker run arguments and the CMD are ignored entirely. Exec form always.
• An entrypoint script without exec. The script stays as PID 1, does not forward SIGTERM and you are back to the ten seconds and the SIGKILL. The last line must be exec "$@", with quotes.
• USER too far up. If you switch user before npm ci, the step fails with EACCES. Install as root, copy with --chown and put USER right before the CMD.
• RUN chown -R after copying. It doubles that layer's size because of copy-on-write. Use COPY --chown.
• An unprivileged user listening on port 80. EACCES: permission denied. Listen on a high port and publish with -p 80:3000.
• HEALTHCHECK without --start-period. The container is marked unhealthy during its legitimate startup and the orchestrator enters a restart loop.
• A healthcheck that queries external dependencies and does not distinguish. If /health returns 503 because the database is down, the orchestrator will restart the API, which is not at fault for anything. For Aurora Libros it is fine in development; in production it is worth separating liveness (is the process alive?) from readiness (can it serve?), and that is covered in lesson 06-05.
• VOLUME in the Dockerfile. It generates orphaned anonymous volumes, it cannot be undone and it silently makes whatever you later write to that path disappear. Decide storage at runtime.
• Tip: put your LABELs in a single instruction, with \ to split lines. Each LABEL is a metadata layer.
• Tip: test the healthcheck command by hand with docker exec before putting it in the Dockerfile. It saves entire build cycles.

Build an image based on alpine:3.21 that:

1. Takes an ARG BUILD_ENVIRONMENT with the default value local.
2. Defines an ENV RUN_ENVIRONMENT from that ARG.
3. Prints both values during the build with a RUN.
4. Prints both when the container runs.

Then:

• Build it without --build-arg and run it. What does each variable print?
• Build it with --build-arg BUILD_ENVIRONMENT=production and run it. What changes?
• Run the image with -e RUN_ENVIRONMENT=overridden. Can you do the same with the ARG?
• Check with docker image history whether the ARG's value is visible. Explain what that implies for passwords.

Create four images based on alpine:3.21, one per row of the table in section 3, using echo as the executable. For each one, run docker run --rm <image> and docker run --rm <image> bye and write down the actual output. Then:

1. Fill in the table with what you observed and compare it with the theoretical one.
2. Explain in one sentence the rule that governs all four rows.
3. Use --entrypoint to run ls / on the image from the fourth row.

The current HEALTHCHECK for aurora-api marks the container unhealthy when PostgreSQL fails, even though the API is working perfectly. Design an alternative:

1. Explain why that is problematic in an orchestrator that restarts unhealthy containers.
2. Propose two different endpoints and what each one should check.
3. Write the HEALTHCHECK you would use in the Dockerfile and justify the choice.
4. Demonstrate with a real container the difference between checking /health (which returns 503 with no database) and checking only that the port responds.

Solution to exercise 1

With --build-arg:

The analysis:

• At build time, both exist. The ENV takes the ARG's value: that is the bridge pattern.
• At runtime, the ARG is always empty. It never reached the container.
• The ENV keeps the value frozen at build time.

Overriding at runtime:

The ENV can indeed be overridden with -e. The ARG cannot, because it does not exist at runtime: -e BUILD_ENVIRONMENT=x would create a brand new environment variable with no relation whatsoever to the build's ARG.

The history:

The value production appears in the clear on the RUN line. If instead of production it had been superSecret2026, anyone pulling the image would read it with a single command and without starting anything. That is exactly why ARG is not suitable for secrets, however much it "disappears" at runtime: it disappears from the environment, not from the history.

Solution to exercise 2

1. The observed table matches the theoretical one. Case 1 with an argument is especially illustrative: bye replaced the entire CMD and Docker tried to run a program called bye, which does not exist. In case 2, bye was appended to the ENTRYPOINT. In cases 3 and 4, bye replaced the CMD but the ENTRYPOINT remained.

2. The rule: ENTRYPOINT is the fixed executable and CMD is its default arguments; what you write after the image name in docker run replaces the CMD only.

3. With --entrypoint:

--entrypoint ls replaces echo, and the / after the image name replaces the CMD, giving ls /. It is the command you will need every time you want to inspect an image with its own ENTRYPOINT:

Solution to exercise 3

1. The problem. The current healthcheck checks /health, which returns 503 if PostgreSQL or Redis do not respond. In Swarm or Kubernetes, an unhealthy container is restarted or replaced. If the database goes down for five minutes, every API replica will be marked unhealthy and will enter a restart cycle despite being perfectly healthy. Worse still: when PostgreSQL comes back, it will meet an avalanche of reconnections from freshly started replicas, with empty caches. A dependency failure has been turned into a total outage and a retry storm.

2. Two endpoints with different responsibilities:

The distinction is the key: restarting fixes a stuck process, but it does not fix a downed database. Faced with a dependency failure, the right thing to do is to stop sending traffic to that replica and wait, not to kill it.

3. The Dockerfile's HEALTHCHECK:

The justification: Docker's HEALTHCHECK has a single state, and its natural consequence is a restart or a replacement. It must therefore reflect liveness. Readiness is queried by the load balancer or the orchestrator on its own — in Compose, with depends_on: condition: service_healthy (lesson 04-02); in Kubernetes, with a separate readinessProbe (lesson 06-05).

The new endpoint in server.js would be as simple as:

4. The demonstration. With the current healthcheck, with no database:

Now overriding the healthcheck at runtime to check only that the port responds:

The same container, with the same missing database, is unhealthy with one check and healthy with the other. The request to /books/abc returns a 400 validation error — without touching PostgreSQL, because the identifier is not an integer — which proves that Express is alive and routing correctly. That is exactly the liveness signal you are after.

Notice in passing the --health-* options of docker run: they let you override an image's healthcheck without rebuilding it, which is extremely handy for experimenting.

Your image has gone from "it works" to "it is professional", and without gaining a single byte. You can tell ARG from ENV by their scope and timing — the first evaporates when the build ends, the second travels inside the container — and you know that neither of them is any good for secrets, because a --build-arg with a password ends up written in the clear in docker image history. You have used ARG before the FROM to parameterize the Node version and be able to test Node 23 without editing a line.

You have mastered the ENTRYPOINT + CMD pairing and its four combinations, with the rule that sums them up: the ENTRYPOINT is the fixed executable, the CMD is the replaceable arguments, and --entrypoint is your way in when you need to debug. You have seen why a docker-entrypoint.sh script must end in exec "$@": without that exec, the script stays as PID 1, does not forward SIGTERM and you are back to the ten-second wait and the SIGKILL. With USER node you have stopped running the API as root — uid=1000 confirmed — installing as root first and copying with --chown so as not to duplicate layers, and you understand why that forces you to listen on 3000 and not on 80.

With eleven OCI labels the image now says who made it, which commit it comes from and when it was built, which is what you need at three in the morning. With HEALTHCHECK, Docker watches the /health endpoint you prepared in lesson 01-07, and you have seen the full starting → unhealthy cycle in docker ps, with the failure history in docker inspect. And you know why VOLUME in a Dockerfile is usually a bad idea — orphaned volumes, an irreversible decision imposed on the user and later writes that vanish without warning — what STOPSIGNAL is for (Nginx needs SIGQUIT) and what ONBUILD and SHELL do in the few cases where they are worth it.

auroralibros/aurora-api:1.1.0 is an image that runs as an unprivileged user, identifies itself, diagnoses itself and stops cleanly in 0.3 seconds. You now know how to build it; next it is worth knowing how to administer it. In the next lesson, Managing Docker Images, you will take care of the local store: listing and filtering with templates, extracting specific fields with inspect --format, auditing with history which layer ate 80 MB, deleting images that have containers using them, understanding where those mysterious <none>:<none> images that pile up build after build come from, cleaning up with the prune family without destroying what you should not, diagnosing disk space with docker system df and taking an image to another machine without any registry at all, with docker save and docker load.