Build Context and .dockerignore
LEVEL 0
The Problem
You run docker build . and it takes forever to start. Docker says “Sending build context to Docker daemon 2.5GB.”
Your project folder has 2.5GB, but your application is only 10MB. What’s happening?
LEVEL 1
The Concept — The Shipping Box
The Concept
When you ship a package, you don’t send your entire house. You put just what’s needed in a box.
The build context is like telling Docker “here’s the box of stuff you might need.” Everything in that directory gets sent to Docker.
If you say “here’s my entire home directory as the context,” Docker packages and sends your entire home directory — even files the build doesn’t need.
.dockerignore is your packing list. It tells Docker “don’t put these things in the box.”
LEVEL 2
The Mechanics — Build Context
The Mechanics
What Is Build Context?
When you run docker build ., the . is the build context — the directory Docker will have access to during the build.
Docker packages this entire directory and sends it to the Docker daemon. Only files in the context can be referenced in COPY/ADD instructions.
Why It Matters
If your context contains:
node_modules/(500MB).git/(200MB)logs/(1GB)- Your actual app (10MB)
Docker sends 1.7GB to the daemon, even if your Dockerfile only copies the 10MB app.
The .dockerignore File
Like .gitignore, but for Docker builds:
# .dockerignore
# Dependencies (will be installed in container)
node_modules/
__pycache__/
venv/
# Version control
.git/
.gitignore
# IDE
.vscode/
.idea/
# Build artifacts
dist/
build/
# Local files
*.log
.env
.env.local
*.tmp
# Docker files (meta, don't need in image)
Dockerfile
docker-compose.yml
.dockerignore
LEVEL 3
.dockerignore Patterns
Basic patterns:
# Ignore file
secret.txt
# Ignore directory
node_modules/
# Wildcard
*.log
temp*
# Double wildcard (any depth)
**/*.pyc
# Negation (exception)
*.md
!README.md
Order matters — later rules override earlier ones.
LEVEL 4
Build Context Best Practices
- Keep the context small — only include what the build needs
- Always use .dockerignore — even for small projects
- Exclude dependencies — they’re installed in the image
- Exclude secrets — never build secrets into images
- Exclude development files — IDE configs, local envs
Performance Impact
| Context Size | Send Time | Impact |
|---|---|---|
| 10 MB | < 1 second | Minimal |
| 100 MB | 2-5 seconds | Noticeable |
| 1 GB | 20-60 seconds | Painful |
| 10 GB | Minutes | Broken workflow |