Building somewhere you do not ship from

Why assemble software in one environment and then throw that environment away?

The straightforward way to package a program is to put everything it needed into one place: the compiler, the headers, the package manager, the source, the test framework, and the finished binary. It all worked together, so ship it all together.

The result is an image of eight hundred megabytes to run a twelve-megabyte binary. And the reflex is to call that waste and start deleting. But hold the question open a moment longer, because there is something more interesting here than size: is the compiler in the shipped image merely surplus, or is it actively a problem? The answer decides whether this is an optimisation or a design principle.

Start with the surplus reading and see how far it gets. A larger image is slower to pull, so deployments and autoscaling are slower, and every node stores more. Real costs, but they are only costs — you would accept them if the toolchain were doing anything useful.

So ask whether it is. Once the binary exists, does the compiler ever run again? It does not. Nor does the package manager, nor the headers, nor the test framework. Every one of them was needed to produce the artifact and none is needed to execute it. Two entirely different jobs, and we assumed they wanted the same environment only because they happened in the same directory.

Now push on what the surplus actually does. Every program in the image is something an attacker who gains execution can use. A compiler lets them build tools in place; a package manager lets them fetch more; a shell and a full set of utilities let them explore. None of that is available in an image containing a binary, its runtime libraries, and nothing else. This is why the size argument, though true, undersells the case — the toolchain is not dead weight, it is capability sitting inside the trust boundary for no reason.

And there is a third cost. The build needed credentials — a token for a private package repository, an SSH key for a private source repository. Ship the build environment and those may still be in it. Recall that image layers are difference archives: deleting a secret in a later instruction only masks it, and anyone who pulls the image can unpack the earlier layer and read it. So a secret that touched a shipped layer is disclosed, whatever the final filesystem looks like.

That last point is decisive, because it rules out the tempting fix. You cannot solve this by cleaning up at the end. Removal is not available to you — an earlier layer cannot be edited. The toolchain has to never enter the chain that ships.

So how? Do the build in a separate stage: a first stage on a fat image with everything the compiler needs, and a second stage that starts from a minimal base and copies in only the produced artifact. The second stage's layer chain has no ancestor in common with the first, so nothing from the build environment travels — not the source, not the toolchain, not the credentials. The first stage still runs, still gets cached, and simply is not published.

Notice how far the second stage can be pared down. A statically linked binary needs almost nothing, so the base can be scratch — literally empty — or a distroless image that carries a runtime and certificate bundle but no shell and no package manager. A dynamically linked program needs its shared libraries and often a certificate store, so scratch will fail at startup with an error that looks mysterious if you have not met it before. And an interpreted language cannot shed its interpreter at all, so the gain there is narrower: you drop the build toolchain and the development headers, but the runtime stays.

That last point is worth keeping honest. The technique is not universal magic. Its size benefit is largest for compiled languages and modest for interpreted ones — but the security benefit, the removal of a shell and a package manager from the shipped image, applies to both.

Three refinements.

First, the misconception: multi-stage builds are usually introduced as a size optimisation, which sets the wrong expectation. Size is the most visible consequence. The design point is that building and running are different activities with different dependencies, and giving each its own environment is the ordinary answer once you have noticed that.

Second, the stages are genuinely independent. The build stage can use a completely different base, a different distribution, even a different language ecosystem, because the only contract between the stages is the file that gets copied forward. That freedom is what lets the build stage be as convenient as you like without any of it reaching production.

Third, minimal does not mean easy. An image with no shell cannot be inspected by opening a shell in it, so debugging moves to other techniques — copying the binary into a fuller image, or attaching an ephemeral debug container. That is a real trade, and it is worth making deliberately rather than discovering it during an incident.

• Distroless and scratch bases, and how to tell which one a given binary can actually use.
• Build secrets mounted for a single instruction so they never enter a layer.
• Debugging an image with no shell: ephemeral containers and copy-out techniques.

Every term the collection defines is gathered in the glossary.