Day 33 of 100
The Container Image Became Huge
🔥 Problem Statement
Nothing is broken — the application works correctly, every release passes its checks. What's changed, gradually, over several releases, is the size of the container image itself: roughly 300 MB not long ago, now sitting around 2.5 GB. Deployments that used to complete quickly now take noticeably longer, purely from the time spent pulling a much larger image on every deploy.
🏗️ Environment
- Dockerfile: single-stage build, general-purpose base image
- Image size: grown from ~300 MB to ~2.5 GB over several releases
- Deployment: image pulled fresh on every deploy
- Symptom: deployments noticeably slower, no functional issue
🤔 Your Challenge
What typically causes container images to grow this dramatically, and how would you bring this one back down?
- Does a single-stage Dockerfile keep anything in the final image that was only needed to build it, not run it?
- What's the difference between a general-purpose base image and one built specifically for running this kind of application?
- Could build artifacts, caches, or dependency layers be accumulating in ways that aren't obvious from the Dockerfile alone?
- How would Docker's layer caching behavior affect what actually ends up in the final image size?
Solution Hidden
Think through the problem yourself before looking at the answer.
💡Solution
Step 1 — Understand the symptoms
A single-stage Dockerfile builds and runs in the same image — which means every build tool, every intermediate build artifact, every package needed only to compile or assemble the application (not to run it) ends up permanently baked into the final image that gets deployed. None of that is needed at runtime, but a single-stage build has no mechanism to leave it behind.
Step 2 — Identify the likely bottleneck
A few things typically compound to produce this kind of growth over successive releases: a general-purpose base image (a full OS distribution) instead of a minimal one built for the actual runtime; build-time dependencies and compilers that get installed but never removed from the final layer; accumulated dependency caches (package manager caches, in particular) that aren't cleaned up within the same layer they're created in; and layers added across successive Dockerfile changes that each individually seemed small but compound because Docker's layer model doesn't automatically shrink a layer when a later layer deletes files from it.
Step 3 — Investigation
docker history <image>Shows the size contributed by each layer in the image — this is usually the fastest way to see exactly which step in the Dockerfile is responsible for the bulk of the growth, rather than guessing.
From there:
- Check the base image — is it a full general-purpose distribution, or is there a slim/minimal variant appropriate for this runtime?
- Check whether build tools and compilers are present in the final image — if the Dockerfile installs a compiler or build toolchain and never removes it (or never separates it from the runtime stage), that's a very common, very large contributor.
- Check whether package manager caches are being cleaned up within the same
RUNinstruction that creates them — cleaning up in a later, separate layer doesn't reduce the image size, because the earlier layer's data is still part of the image history. - Check for accidentally copied build artifacts, test fixtures, or documentation — a broad
COPY . .without a.dockerignorecan pull in far more than the application actually needs.
Step 4 — Recommended action
Move to a multi-stage build: one stage installs build tools, compiles, and produces build artifacts; a separate, final stage starts from a minimal base image and copies over only the compiled artifacts and runtime dependencies actually needed to run the application. Everything used only for building — compilers, build caches, source files not needed at runtime — never makes it into the final image at all, because it was never part of that stage.
Switch to a minimal base image appropriate for the runtime (a slim or distroless variant, where compatible) instead of a general-purpose one. Add or tighten a .dockerignore to prevent unnecessary files from being copied into any build context. Clean up package manager caches within the same layer they're created, not a later one.
Step 5 — Engineering lesson
Docker's layer model means a Dockerfile's history matters as much as its final state — deleting a file in a later layer doesn't shrink the image, because earlier layers are preserved as-is. A single-stage build that mixes "everything needed to build" with "everything needed to run" will accumulate size over time by design, and the fix isn't a one-off cleanup, it's restructuring the build so build-time and run-time concerns are genuinely separated.
🧠 Today’s Takeaway
Smaller images improve speed, security and operational efficiency.
🔔 Don’t Miss Tomorrow’s Challenge
A new real-world engineering challenge is released every day.
100 Days → 100 Challenges → 100 New Things Learned.
Get the useful stuff, not the noise.
Occasional notes on engineering, Platform Engineering, AI, cloud and things I’m learning along the way.

