Dockerfile Best Practices Checklist for Smaller, Safer Images

Overview

A good Dockerfile is more than a set of commands that produces a working container. It is also a build specification, a security boundary, and part of the operational documentation for your service. The goal is not to make every image as small as possible at any cost. The goal is to create an image that contains what the application needs, excludes what it does not need, builds predictably, and behaves clearly when deployed.

Start by identifying the runtime requirements of the application. A compiled backend may need only its executable and a small runtime base image. A JavaScript service may need production dependencies, certificates, and a configured non-root user, but not the package manager cache or source-control metadata. A development image has different requirements from a production image, so avoid treating one Dockerfile target as the answer for every environment.

Use this checklist alongside your existing release process. For example, image build and scan steps can fit naturally into a GitHub Actions deployment checklist. If you are still establishing a local workflow, the local development environment guide can help separate development dependencies from deployment concerns.

Checklist by scenario

For every Dockerfile

• Choose an intentional base image. Select an image that matches the application runtime and remove unnecessary tools. Prefer a clearly maintained tag strategy, and document why the chosen variant is appropriate. Avoid relying on an unqualified, floating choice when reproducibility matters.
• Add a useful .dockerignore file. Exclude version-control directories, local dependency folders, build output that will be recreated, environment files, logs, editor metadata, and other material that does not belong in the build context. A smaller context can also make builds easier to inspect.
• Copy files in a deliberate order. Copy dependency manifests before application source when the dependency installation step can be cached independently. Then copy the source needed to build or run the service. This prevents a small source change from unnecessarily invalidating expensive dependency layers.
• Combine related cleanup with installation. If a package manager creates temporary indexes or caches, remove them in the same build step where they are created. Deleting them in a later layer may not reduce the stored image history as expected.
• Use explicit commands and paths. Set the working directory, define the required startup command, and avoid hidden assumptions about the shell or current directory. An explicit Dockerfile is easier for another developer to review and modify.
• Keep secrets out of the image. Do not copy credentials, private keys, tokens, or local environment files into the build context. Build-time credentials should use an appropriate secret mechanism supported by the build workflow, and runtime secrets should be provided by the deployment environment.

When reducing image size

• Use a multi-stage Docker build. Put compilers, test tools, development headers, and package managers in a builder stage. Copy only the required runtime artifacts into the final stage. This is one of the most reliable ways to reduce a production image without weakening the build process.
• Install only production dependencies. Separate development and runtime dependency installation where the ecosystem supports it. Confirm that the application does not require a tool that was removed simply because it was classified as a development dependency.
• Measure before and after. Inspect image layers and compare build output rather than assuming that a shorter Dockerfile is smaller. Large assets, duplicate dependencies, copied source trees, and generated files are common causes of unexpected growth.
• Do not remove required runtime files for size alone. Certificates, timezone data, native libraries, user records, and diagnostic information may be necessary for correct operation. Validate the image with the same kinds of requests and background jobs it will handle after deployment.

When hardening for deployment

• Run as a non-root user. Create or select a dedicated application user, ensure it can read and write only the paths it needs, and switch to that user before the final startup command. Test file permissions during the image build or in a container test.
• Use a predictable filesystem layout. Keep application files in a known working directory, make writable directories explicit, and avoid granting broad write access to the entire filesystem.
• Add a health check when it reflects real readiness. A health check should test a meaningful local condition, not merely whether a process exists. If readiness depends on external services, define that behavior with care so a temporary dependency failure does not produce misleading container status.
• Scan the built image. Run vulnerability and configuration checks in the delivery workflow, review findings in context, and establish a process for updating the base image and direct dependencies. Scanning is most useful when it leads to an owner and a remediation decision.

What to double-check

Also inspect the build context and final image as separate objects. A clean final image does not make an accidentally exposed build context acceptable. Likewise, a small image does not prove that the startup command, permissions, network behavior, or shutdown handling are correct.

For services that expose APIs, test the container with representative requests, authentication flows, and error responses. A deployment that starts successfully can still fail once browser or client behavior is involved; the CORS troubleshooting guide and JWT decoder guide are useful follow-ups when those issues appear at the application boundary.

Common mistakes

• Using a development image in production. Development tools are convenient, but they enlarge the attack and maintenance surface. Define separate development and production targets when their needs differ.
• Copying the entire repository too early. This often invalidates dependency caches and may include tests, credentials, build artifacts, or local configuration.
• Assuming a smaller base image is automatically better. A minimal image can make debugging, certificate handling, or native-library support more difficult. Choose based on runtime behavior and maintenance needs.
• Passing secrets through ordinary build arguments. Values can be exposed through build history, logs, or metadata depending on the workflow. Use a mechanism intended for secrets and verify what is retained.
• Adding a health check without defining health. A command that returns success is not necessarily evidence that the application can serve useful traffic. Align the check with the service’s readiness model.
• Ignoring file ownership after switching users. The process may start but fail when it writes uploads, temporary files, caches, or generated configuration. Test those paths under the final user.
• Scanning once and treating the result as permanent. Base images and dependencies change. A scan belongs in a repeatable workflow, followed by a clear review of actionable findings.

When to revisit

Review the Dockerfile whenever you add a dependency, change the runtime version, alter the build command, introduce a new writable directory, or move the service to a different deployment platform. Revisit it before a production launch, after a significant image-size increase, when a scan reports a serious issue, and during routine dependency or base-image maintenance.

It is also worth scheduling a broader review before seasonal planning cycles or other periods when teams change infrastructure and release workflows. Check whether the base-image policy, build cache configuration, secret handling, scan rules, and runtime assumptions still match the organization’s current process. Docker features and CI behavior can evolve, so confirm syntax and workflow options against the documentation for the versions you actually use rather than copying an old example unchanged.

For a practical final pass, build the image from a clean checkout, inspect the resulting layers, run it with the intended non-root user, exercise its important endpoints, and verify that no credentials entered the context or image. Then record the remaining trade-offs in the repository. A concise note explaining why an image is larger, why a health check is limited, or why a particular base was selected can save future maintainers from repeating the same investigation.

Once the Dockerfile passes this checklist, connect it to the rest of the delivery system: automated tests, image scanning, deployment review, and post-deployment monitoring. The result is not merely a smaller image. It is a clearer and more repeatable path from source code to a container that the team can build, ship, and maintain with confidence.