I want to tell you about the day I found out our “small Go microservice” was shipping to production as a 1.2GB Docker image. A deploy that normally takes twenty seconds took four minutes, and I went digging for the cause like it was somebody else’s fault. It wasn’t. The Dockerfile was mine, and the 900MB of Go toolchain riding along to production was very much mine.<\/p>\n
The fix took fifteen minutes and one feature: the multistage build. It has been in Docker since version 17.05, which is to say, since 2017. I’d read about it. I’d nodded along at conference talks about it. I just hadn’t done it, because the fat image worked fine and nothing forces you to look at image sizes until something hurts.<\/p>\n
Short version for the impatient: compile your app in one stage, copy the result into a tiny runtime stage, and ship only that second stage. If you want the actual Dockerfiles and the traps I hit along the way, keep reading.<\/p>\n
A Dockerfile can contain more than one That’s the entire trick. The official multi-stage build docs<\/a> explain it in about a page, which is roughly the length the feature deserves. It matters because build dependencies and runtime dependencies are wildly different sizes. The Here’s a lightly anonymized version of my original Dockerfile:<\/p>\n Six lines. It builds, it runs, it passes CI, and it quietly packs the whole Go toolchain, the module cache, and every file in my repo into the production image. My None of this was a mystery. It was just invisible, because nothing in the normal dev loop ever shows you the number. The image built, the container started, the endpoints answered. Everyone was happy until the registry bill and the deploy times stopped being happy.<\/p>\n Here’s the replacement:<\/p>\n The final image is 12MB. Same binary, same behavior, roughly one percent of the size.<\/p>\n A few choices worth explaining. For the runtime stage I used distroless<\/a>, Google’s family of minimal base images. The Go is the easy case because the compiler hands you one file. Node can’t compile away That ships your dev dependencies, your TypeScript source, and the npm cache. After:<\/p>\n The The tutorials make this look frictionless. It mostly is, but I lost real time to four things.<\/p>\n TLS certificates. If you use Alpine and musl. If you build with CGO enabled on a glibc system and run the binary on Alpine, it won’t start, because Alpine uses musl instead of glibc. Either keep The build context still matters. Multistage builds don’t fix a missing You can target intermediate stages. Running The size win gets the headlines, but the security win is probably worth more. Every package in your image is something a scanner can flag and an attacker can potentially use. A distroless runtime has no shell, so a whole class of reverse shells and container escapes simply has nothing to execute. Docker’s own best practices guide<\/a> recommends multistage builds for exactly this reason.<\/p>\n I covered the rest of my hardening routine in my Docker security checklist<\/a>, and multistage builds sit at the top of it on purpose: they shrink the attack surface without changing a line of application code. It’s the same advice I give clients in my consulting work<\/a> when they ask where to start with container security. Start with what’s in the image, because the safest package is the one that isn’t there.<\/p>\n Run My bet: your first multistage conversion cuts at least 70 percent, and afterward you’ll be mildly annoyed that nobody made you do this earlier. I certainly was.<\/p>\n","protected":false},"excerpt":{"rendered":" I cut a 1.2GB Go service image down to 12MB with a Docker multistage build. The before and after Dockerfiles, the base images I picked, and the traps I hit.<\/p>\n","protected":false},"author":2,"featured_media":560,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"I cut a 1.2GB Go service image down to 12MB with a Docker multistage build. The before and after Dockerfiles, the base images I picked, and the traps I hit.","rank_math_focus_keyword":"docker multistage build","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[302,45],"tags":[127,80,125,126,623],"class_list":["post-561","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops","category-programming","tag-containers","tag-devops","tag-docker","tag-dockerfile","tag-multistage-build"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/561","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=561"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/561\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/560"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=561"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=561"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=561"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}FROM<\/code> line. Each FROM<\/code> starts a new stage with a fresh filesystem, and later stages can pull files out of earlier ones with COPY --from<\/code>. The final image contains only the layers of the last stage. Everything else, the compiler, the package caches, your source code, gets discarded when the build finishes.<\/p>\ngolang<\/code> base image is over 800MB. A compiled Go binary is often under 15MB. Shipping the first to run the second is like mailing someone a cake inside the oven you baked it in.<\/p>\nThe before: what I was actually shipping<\/h2>\n
FROM golang:1.24\nWORKDIR \/app\nCOPY . .\nRUN go build -o server .\/cmd\/server\nEXPOSE 8080\nCMD [".\/server"]\n<\/code><\/pre>\n.dockerignore<\/code> was also missing, so COPY . .<\/code> was hauling in the .git<\/code> directory too. If you’ve never checked, run docker history<\/code> on one of your images. Mine read like a confession.<\/p>\nThe after: two stages and a 12MB image<\/h2>\n
# Stage 1: build\nFROM golang:1.24 AS build\nWORKDIR \/app\nCOPY go.mod go.sum .\/\nRUN go mod download\nCOPY . .\nRUN CGO_ENABLED=0 go build -ldflags="-s -w" -o \/server .\/cmd\/server\n\n# Stage 2: run\nFROM gcr.io\/distroless\/static-debian12\nCOPY --from=build \/server \/server\nEXPOSE 8080\nENTRYPOINT ["\/server"]\n<\/code><\/pre>\nCGO_ENABLED=0<\/code> produces a fully static binary, which means the runtime stage needs no libc at all. The -ldflags=\"-s -w\"<\/code> flags strip debug symbols, which took another 30 percent off my binary. And copying go.mod<\/code> and go.sum<\/code> before the rest of the source means Docker can cache the dependency download layer, so rebuilds after a code change skip the slowest step.<\/p>\nstatic-debian12<\/code> variant is around 2MB and contains CA certificates, a timezone database, and almost nothing else. No shell, no package manager, no curl<\/code>. That felt weird at first. It stops feeling weird the first time you read a CVE report and realize none of the affected packages exist in your image.<\/p>\nNode is messier, but it still works<\/h2>\n
node_modules<\/code>, so the win is smaller, but it’s still real. Before:<\/p>\nFROM node:22\nWORKDIR \/app\nCOPY . .\nRUN npm ci && npm run build\nCMD ["node", "dist\/server.js"]\n<\/code><\/pre>\nFROM node:22 AS build\nWORKDIR \/app\nCOPY package*.json .\/\nRUN npm ci\nCOPY . .\nRUN npm run build\nRUN npm prune --omit=dev\n\nFROM node:22-slim\nWORKDIR \/app\nENV NODE_ENV=production\nCOPY --from=build \/app\/node_modules .\/node_modules\nCOPY --from=build \/app\/dist .\/dist\nCMD ["node", "dist\/server.js"]\n<\/code><\/pre>\nnpm prune --omit=dev<\/code> line drops everything your build needed but your runtime doesn’t, and the node:22-slim<\/code> base is a few hundred MB lighter than the full image. On the one Node service I maintain, this change took the image from 1.1GB to about 210MB. Not 12MB. I’m not going to pretend Node gives you the Go ending, but an 80 percent cut is worth six extra lines.<\/p>\nThe traps I hit so you don’t have to<\/h2>\n
FROM scratch<\/code> instead of distroless, your image contains literally nothing, including CA certificates. My first attempt built fine and then failed every outbound HTTPS call. Distroless includes the certs; scratch doesn’t. That difference cost me an hour of staring at x509 errors before I understood what was missing.<\/p>\nCGO_ENABLED=0<\/code> or do the build itself on an Alpine builder image. I knew about this one only because it bit a colleague the month before it would have bitten me.<\/p>\n.dockerignore<\/code>. Docker still uploads your entire directory to the daemon before the first stage runs, so a bloated context slows every build even if none of it reaches the final image. Add .git<\/code> and node_modules<\/code> to .dockerignore<\/code> anyway.<\/p>\ndocker build --target build .<\/code> gives you the fat builder stage as its own image, which is handy when you need a shell and a compiler to debug something. I went weeks thinking multistage meant giving that up. It doesn’t.<\/p>\nSmaller images are also safer images<\/h2>\n
What to do this week<\/h2>\n
docker images<\/code> and sort by size. Pick the fattest image you own, split its Dockerfile into a build stage and a runtime stage, and measure the difference. On most services it’s a fifteen minute change. If you want to see exactly where the bytes went, dive<\/a> will show you the layers one by one.<\/p>\n