What is a .dockerignore file and why is it important?

Direct Answer

.dockerignore removes matching paths from the build context sent to the builder. This can reduce transfer and cache invalidation and can stop an accidental COPY . . from seeing local files. It does not automatically shrink an image whose Dockerfile never copied those files, and it is not a secret-management boundary.

Deep Dive & Architecture

The build context is the set of files made available to the builder. .dockerignore is evaluated before those files are sent, so a matching file cannot be read by a normal COPY or ADD from that context.

This improves builds in two ways: fewer bytes are transferred, and irrelevant changes—such as .git data or local logs—do not keep invalidating a broad COPY . . step. It only changes image size if the Dockerfile would otherwise copy those files.

Treat it as hygiene, not a secret vault. Credentials may leak through build arguments, command history, logs, another context, or a deliberate override. BuildKit secret mounts provide sensitive data to a build step without baking it into the final layer when used correctly.

Code Example

FROM eclipse-temurin:17-jre-alpine

WORKDIR /app

COPY target/order-service-0.0.1-SNAPSHOT.jar app.jar

EXPOSE 8080

ENV SPRING_PROFILES_ACTIVE=prod

ENTRYPOINT ["java", "-jar", "app.jar"]

Common Mistakes & Pitfalls

• Not creating one at all: Freshers skip .dockerignore entirely and wonder why docker build takes 30 seconds just to send context. Without it, Docker uploads every file in the directory, including target/ with 200MB of dependencies and class files.
• Excluding the JAR you need: Freshers copy their entire .gitignore into .dockerignore, which excludes target/ containing the JAR. If your Dockerfile says COPY target/app.jar, the build fails because target/ is ignored. Solution: exclude target/ in .dockerignore but COPY target/*.jar explicitly before building the image, or build the JAR inside a multi-stage Docker build.
• Not excluding .env files: Local environment files with database passwords or API keys get copied into the image if not explicitly excluded. These secrets then persist in image layers even if deleted later — anyone with access to the image can extract them using docker history.