Lorixen.
EN

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

  • .env files with database passwords, payment keys and email credentials.
  • The .git folder, 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
  • .env and .env.*, with an exception like !.env.example if you want the template included
  • node_modules, vendor, .venv and other dependency folders you install inside the image
  • dist, build, coverage and other generated output
  • *.log, tmp, uploads and local data folders
  • Editor and system files such as .DS_Store and .idea
  • Dockerfile and docker-compose*.yml themselves, 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.json and the lock file), install dependencies, then copy only the source folders the app needs, such as src and public.
  • 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

  1. Look at the context size reported at the start of a build. If it's large, the ignore file is missing something.
  2. 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.
  3. Search for secrets: check for .env, .git and key files. Secret-scanning tools can scan images as well as repositories.
  4. Review image history with docker history to 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 .dockerignore and 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.

Sources

WhatsAppBook a call