how to shrink a bloated Docker build context

TL;DR

A bloated build context means Docker tars up gigabytes (node_modules, .git, build artifacts) and ships them to the builder on every build, before the Dockerfile even runs. Fix it with a strict .dockerignore, verify the context size after, and restructure so the Dockerfile only sees what it needs. Context problems are always about what you failed to exclude.

The query

how to shrink a bloated Docker build context

Use this when

• Builds stall while sending the build context
• The context is hundreds of MB or GB
• You suspect secrets or junk ship inside the context
• CI builds are slow before the first Dockerfile step

Not for when

• Slow Dockerfile steps (layer caching, different topic)
• Multi-stage build optimization
• Registry push speed

Steps

Step 1: Measure the context size

Check how big the context actually is. The build output or a dry tar of the directory tells you. If it is tens of MB, the context is not your problem; if it is GB, keep going. Expected output: a number. The usual shock is discovering node_modules and .git dominate it.

Step 2: Write a strict .dockerignore

Exclude aggressively: version control directories, dependency directories that get reinstalled in the image, local build outputs, editor files, docs, and test fixtures not needed at runtime. When in doubt, exclude it; add back only what the build proves it needs. Expected output: context size drops by an order of magnitude or more.

Step 3: Verify what the context actually contains

List the files that would be sent. Confirm nothing sensitive is in there: env files, credentials, private keys. The context ships to the builder; anything in it is visible in layer history if copied into the image. Expected output: a clean file list with no secrets and no junk.

Step 4: Restructure if the Dockerfile needs files from everywhere

If the build legitimately needs files scattered across the repo, the context will always be big. Restructure: build from a subdirectory, or use multiple build stages with separate contexts. Do not let one needed file justify a 2GB context. Expected output: the Dockerfile's context contains only its inputs.

Step 5: Keep it small with CI checks

Add a check that fails the build if the context exceeds a threshold. Contexts bloat again silently as repos grow; the check keeps the fix permanent. Expected output: future bloat gets caught at PR time, not discovered during the next slow build.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_n4jdXLITEIokcSlNM1jGpA