The auroralibros/aurora-api:1.2.0 image weighs 142 MB. That is not a disaster, but it is not optimized either: a C compiler travels inside it, along with the development dependencies and files nobody ever runs. In this lesson you put it on a diet measuring at every step, down to a specific figure, without losing any of the hardening from lesson 05-03.

1. Why size matters and what must not be sacrificed
2. Measure first: image ls and history
3. dive: exploring layer by layer
4. Choosing the base, with numbers
5. Multi-stage builds: the concept
6. Multi-stage applied to aurora-api
7. Named stages and --target
8. A common base image for several images
9. Reducing layers and content
10. Deleting a file does not reduce the size (demonstrated)
11. Ordering for the cache
12. Final verification and summary table

On a platform with five nodes and fifteen deployments a month, shaving 40 MB off an image means roughly 3 GB less transfer per month and tens of seconds less on every cold start.

And what you do not sacrifice in exchange for weight: the HEALTHCHECK, the unprivileged user, the OCI labels for traceability, the ability to diagnose a production problem, and the reproducibility of the build. A 40 MB image nobody knows how to debug at three in the morning is a bad deal.

The diagnosis is immediate and it surprises almost everybody the first time: of the 142 MB, 115 MB are the base image. The dependencies are 21 MB and your own code, 3 MB. The main lever is not in your code: it is in which base you pick and what you add on top of it.

To compare precisely, use the real size (docker image inspect --format '{{.Size}}' | numfmt --to=iec) and not the one the registry shows, which is compressed and always looks smaller.

docker history tells you how much each layer weighs; dive tells you what is inside it and how much is wasted.

Three findings and three decisions: the npm cache should not be in the final image, node_modules/.cache is build junk, and .git should never have entered the build context in the first place (there is a line missing from .dockerignore).

The efficiency score measures how much content is written into one layer and then overwritten or deleted in another; below 95% there is work to do. To automate it in CI, add -e CI=true and --lowestEfficiency=0.95: dive exits with a non-zero code if the threshold is not met.

Alpine's trade-off has a name: musl instead of glibc. The real consequences:

• npm packages with binaries precompiled for glibc may not work and may have to be compiled on install (slower, and it requires build-base).
• Some DNS-heavy or name-resolution-heavy workloads behave differently under musl.
• Certain scientific and machine-learning libraries do not support musl.

aurora-api uses Express, pg and redis, none of which has problematic native dependencies: Alpine is the right choice. If one day a dependency caused trouble, node:22-slim costs 95 MB more and fixes it.

A multi-stage build uses several base images in the same Dockerfile. The intermediate stages compile and prepare; the final stage copies only the result. Everything else —compilers, caches, development dependencies, source code— stays out of the published image.

Two rules that sum up the mechanism:

• Only the last stage (or the one named with --target) ends up in the image; the rest are discarded.
• COPY --from=<stage> brings specific files over from an earlier stage, and nothing else travels: not its layers, not its history, not its secrets.

The starting point (a single stage, 142 MB) and the destination:

142 MB → 121 MB: 15% less with a single structural change. Where do those 21 MB come from? From build-base (python3, make, g++), which used to be installed in the final image and now lives and dies inside the dependencies stage, and from the npm cache.

Notice that none of the hardening has been lost: USER node, the HEALTHCHECK, the OCI labels and the exec-form ENTRYPOINT/CMD are all still there. Optimizing is not trimming security.

Named stages are not just organization: they are separately buildable artifacts.

The development image weighs 318 MB and that is exactly as it should be: it carries the devDependencies, the test framework and the debugging tools. It is precisely the target: development that compose.override.yaml has been using since lesson 04-07, and now you can see where it comes from.

A very useful pattern is a test stage that fails the build if the tests fail:

BuildKit does not run that stage when building the production one, because it is not part of its dependency graph (lesson 05-05). It only runs if you ask for it with --target.

When you publish several Node services, it pays to have your own base with everything they share:

Advantages: a single security update propagates to every service, the base layer is shared on disk and on download between them, and the shared decisions live in one place. Downside: you create an internal dependency that has to be maintained and versioned. It starts to pay off from three or four services onwards.

aurora-api's .dockerignore after what dive revealed:

From a 94 MB directory to 812 kB of context. That does not only make the build faster: it guarantees that .git and .env cannot sneak into any layer, which is a security matter as much as a size one.

The file does not exist and the image still weighs 113 MB. The explanation is the one from lesson 05-02: layers are immutable, and rm in a later layer only creates a whiteout that hides the file; the 105 MB are still down there, downloaded on every pull and stored on every node.

The fix is to combine creation and deletion in the same instruction:

From 113 MB to 8.15 MB. The same logic, the same functional result, one && of difference. And it is exactly the reason for --virtual .build in the Dockerfile from section 6: install, compile and uninstall inside a single RUN.

A reminder from lesson 02-02, now combined with multi-stage: instructions are ordered from least to most likely to change.

With multi-stage the effect is multiplied: when you touch src/server.js, BuildKit reuses the entire dependencies stage —including the npm install— and only rebuilds the last two layers of the final stage.

Three seconds against the forty-odd of a clean build. Optimizing size and optimizing build speed are, almost always, the same job.

An optimized image that does not work is worth nothing. The check is mandatory:

And the final step up, if your context allows it: switching the final base to distroless.

142 MB → 102 MB: 28% less. The price, already familiar from lesson 05-03: with no sh there is no docker exec ... sh, and the wget-based HEALTHCHECK stops working, so the probe moves to Compose or to the orchestrator.

Optimizing without measuring. Without docker history and dive, you trim where it does not hurt and leave the 100 MB layer untouched.

Deleting files in a later RUN. The file disappears and the space does not. Creation and deletion belong in the same instruction.

Copying the whole project with COPY . . and no .dockerignore. In come .git, node_modules and, if you are lucky, some .env.

Installing build tools in the final image. Compilers in production are weight and attack surface. They belong in the dependencies stage.

Sacrificing the HEALTHCHECK or the USER to save a few megabytes. It is a terrible trade: security and operability are worth more than 3 MB.

Chasing the absolute minimum. A binary on scratch that you cannot debug costs more in its first incident than it saved in a year of downloads.

Tip: build measurement into your workflow. A CI step that compares the image's size with the previous version's and warns if it grows by more than 10% catches the bloated dependency on the day it lands, not six months later.

Exercise 1. Analyze auroralibros/aurora-api:1.2.0 with history and with dive: identify the largest layer, work out what percentage of the total the base represents, and find at least one genuine piece of waste you can remove with .dockerignore.

Exercise 2. Convert aurora-api's Dockerfile to multi-stage with three stages (dependencies, development, production), measure before and after, and prove that the final image does not contain the compiler that is indeed in the dependencies stage.

Exercise 3. Prove that deleting a file in a later layer does not reduce the size, and fix it. Work out the exact saving and explain what would have happened if that file had been a credentials file.

Solution 1.

81% of the image is the base. That is the number that reorders your priorities: fighting over the 3 MB of your own code is irrelevant until you consciously decide which base you use. With dive the specific waste shows up:

.git inside a production image is not just 1.2 MB of weight: it is the repository's full history traveling through the registry, along with any secret somebody committed and later deleted. It is fixed with one line in .dockerignore, and the check is straightforward:

Solution 2.

The dependencies stage has the three build binaries; the final one, none. And yet both have the same 64 packages in node_modules: COPY --from=dependencies has brought over exactly the result of the work and none of the tooling that produced it.

That is the central idea of multi-stage put as plainly as possible: what you need in order to build is not what you need in order to run. And the benefit is not only about size; it is also about security, because an attacker with command execution in the final image finds no compiler with which to prepare the next phase of their attack.

Solution 3.

The exact saving is 104.85 MB, 92.8% of the total, and the functional result is identical: in both images the file does not exist. The difference lies in whether those 100 MB ever became part of a consolidated layer. In bad, layer A wrote them and they became immutable; layer B only added a whiteout that hides them. In good, the file was born and died inside the same instruction, so by the time BuildKit consolidated the layer it was already gone.

The question about credentials takes the demonstration to its most uncomfortable conclusion:

The file does not exist and the password is recovered from the exported layer in a single command. If that image had been published on Docker Hub, anybody could extract it with docker pull and docker save, without ever running the container. That is why the same && that saves 105 MB is also a security control, and why the right solution for build-time secrets is not an && but RUN --mount=type=secret, which you will see in the next lesson.

aurora-api has gone from 142 MB to 102 MB, 28% less, without losing the unprivileged user, the HEALTHCHECK, the OCI labels or a single endpoint: /health, /books and /books/:id respond exactly as before and the container still reaches healthy. And, more important than the figure, you have the method: measure first. docker image ls for the total, docker image history to find the fat layer —which turned out to be the base, at 81% of the weight— and dive to see the real waste, which uncovered the npm cache and a .git that should never have entered the context.

You know how to choose a base deliberately rather than out of habit, aware of the musl-versus-glibc trade-off and of what each step between node:22, -slim, -alpine, distroless and scratch costs. You have mastered multi-stage builds: a stage that installs and compiles with build-base, a development stage with the devDependencies that feeds the target: development in your compose.override.yaml, a test stage that breaks the build if something fails, and a final one that receives only node_modules and src/ through COPY --from —demonstrated: three compilers in the intermediate stage, zero in the published one. And you know how to build each one separately with --target, as well as how to share a base image of your own across several services.

On the content side: --no-cache, --no-install-recommends, --virtual with its apk del, npm ci --omit=dev, npm cache clean and a .dockerignore that shrank the context from 94 MB to 812 kB. And the demonstration most worth remembering: deleting a file in a later layer does not reduce the size —113 MB versus 8.15 MB for one &&— and that same mechanism means a credential that was written and then deleted is still extractable from the published image.

Lesson 05-05 brings on stage the builder that has been doing all of this underneath: BuildKit, with its dependency graph and its parallelism between stages, and Buildx with its builders. You will see mounts in RUN —type=cache so you do not reinstall npm on every build, type=bind, type=tmpfs and above all type=secret, the correct answer to the credentials problem you have just demonstrated—, remote shared cache with --cache-from and --cache-to, multi-architecture builds for amd64 and arm64 with their manifest lists, and docker buildx bake to build every Aurora Libros image in one go.