Keep secrets and junk out of Docker images with .dockerignore
Short answer: When you run docker build ., Docker sends everything in that folder to the builder as the build context, and a COPY . . line puts all of it into your image. Without a .dockerignore file, that can include your .env file, Git history, local databases, logs and node_modules, making images bigger, builds slower and secrets readable by anyone who can pull the image. Add a .dockerignore that excludes them, copy only what the app needs, and pass build-time secrets with secret mounts rather than build arguments.
What the build context is
Docker's documentation on build context explains that a build uses a set of files, usually the folder you point docker build at, and that instructions such as COPY and ADD can only use files from that context. The whole context is packaged up and sent to the builder before the build starts.
Two problems follow:
- Everything in the folder travels, even files the Dockerfile never uses. Large folders make every build slower.
- Broad copy instructions copy everything, so
COPY . .puts every file from the context into the image layer.
Images are often pushed to registries, shared with contractors, deployed to several servers or kept for months. Anything inside them can be extracted by anyone with access, even files you delete in a later layer.
What typically leaks
.envfiles with database passwords, payment keys and email credentials.- The
.gitfolder, with your full history, including secrets that were committed and removed years ago. - Local database files, uploads and test data with real customer details.
- Cloud credentials or SSH keys sitting in a project folder.
- Debug logs and crash dumps.
node_modules, virtual environments and build output from your own machine, which bloat the image and may not even work on Linux.
Writing a .dockerignore
Docker's documentation explains that a .dockerignore file excludes files and directories from the build context. Put it next to your Dockerfile at the root of the context. A sensible starting point for a web app:
.git.envand.env.*, with an exception like!.env.exampleif you want the template includednode_modules,vendor,.venvand other dependency folders you install inside the imagedist,build,coverageand other generated output*.log,tmp,uploadsand local data folders- Editor and system files such as
.DS_Storeand.idea Dockerfileanddocker-compose*.ymlthemselves, if they don't need to be inside the image
Patterns work much like .gitignore, though not identically; check Docker's syntax notes for details such as how exceptions with ! behave.
Copy deliberately, not everything
Even with a good ignore file, prefer explicit copies:
- Copy dependency manifests first (
package.jsonand the lock file), install dependencies, then copy only the source folders the app needs, such assrcandpublic. - In multi-stage builds, copy only the built output into the final stage.
An allowlist approach is safer than relying on the ignore file alone. If someone adds a new secret file later, it won't be swept in by accident.
Never pass secrets as build arguments
Some builds need a secret while building, for example a token to install private packages. It's tempting to use ARG or ENV. Docker's build secrets documentation is clear that build arguments and environment variables are inappropriate for secrets, because they persist in the final image. Use secret mounts instead: pass the secret with docker build --secret, and mount it only in the RUN step that needs it. It's available during that step and isn't stored in the image.
Runtime secrets, such as database passwords, should be supplied when the container starts, through your platform's secret settings or environment configuration, not baked into the image at all.
Check what's in your image
- Look at the context size reported at the start of a build. If it's large, the ignore file is missing something.
- List files in the image: run a shell in a container from the image and look in the app directory, or use an image inspection tool.
- Search for secrets: check for
.env,.gitand key files. Secret-scanning tools can scan images as well as repositories. - Review image history with
docker historyto spot layers that added unexpected files.
Make it part of review
Treat Dockerfile and .dockerignore changes like security-sensitive code. When someone adds a new folder to the project, such as an exports directory or a local cache, ask whether it needs an ignore entry. When a Dockerfile gains a broad COPY, ask what it pulls in. A short checklist in your pull request template, covering secrets, generated files and image size, catches most mistakes before an image is ever pushed to a registry.
If secrets have already shipped
If an image containing real secrets was pushed anywhere others can pull it:
- Rotate the secrets first. Assume they're exposed.
- Delete or replace the affected image tags in your registry.
- Rebuild with the fixed
.dockerignoreand explicit copies. - Check the registry's access settings, especially for images accidentally made public.
A worked example
Take a hypothetical Winnipeg property-management startup whose Docker image for its tenant portal had grown large and slow to deploy. While investigating, a developer found the image contained the project's .git folder and a .env file with live database and email credentials, copied in by COPY . .. They rotated every credential in the file, added a .dockerignore for Git data, environment files, dependencies and build output, changed the Dockerfile to copy only the needed folders, and moved a private package token to a build secret mount. The image shrank considerably and the next scan found no secrets.
FAQ
Does .dockerignore affect docker compose builds?
Yes. Compose builds use the same build context rules, so the same file applies.
Can I have different ignore files for different Dockerfiles?
Docker supports Dockerfile-specific ignore files placed next to each Dockerfile. Check the documentation for the naming rule.
Is deleting a file in a later layer enough?
No. It remains in the earlier layer and can be extracted.
Do I still need .gitignore?
Yes. They serve different tools; keep both.
If you'd like your container images checked for leaked files and secrets, tell us how you build them.