Dockerfile

Guidance on Dockerfile build instructions, package management and container runtime settings.

Documentation

Article Path
Use COPY instead of ADD dockerfile/add_instead_of_copy
CMD and ENTRYPOINT without JSON form dockerfile/not_using_json_in_cmd_and_entrypoint_arguments
Review COPY file ownership and write permissions dockerfile/chown_flag_exists
COPY --from references its own build stage dockerfile/copy_from_references_current_from_alias
Review the intent of FROM platform selection dockerfile/using_platform_with_from
Review container health-check configuration dockerfile/healthcheck_instruction_missing
Use of the MAINTAINER instruction dockerfile/maintainer_instruction_being_used
Working directory set with RUN cd dockerfile/run_command_cd_instead_of_workdir
Review apt use in Dockerfile automation dockerfile/run_using_apt
Using sudo in RUN dockerfile/run_using_sudo
Changing the default shell with RUN dockerfile/changing_default_shell_using_run_command
Review the container SSH port declaration dockerfile/exposing_port_22
Dockerfile has no USER instruction dockerfile/missing_user_instruction
Review apk installation cache management dockerfile/apk_add_using_local_cache_path
apk package versions are not pinned dockerfile/unpinned_package_version_in_apk_add
Missing package version pins in apt-get installs dockerfile/apt_get_install_pin_version_not_defined
Review apt-get installation prompts dockerfile/apt_get_missing_flags_to_avoid_manual_input
Review apt-get recommended package installation dockerfile/apt_get_not_avoiding_additional_packages
Review apt-get package-list cleanup dockerfile/apt_get_install_lists_were_not_deleted
Review dnf installation cache cleanup dockerfile/missing_dnf_clean_all
Review dnf installation prompts dockerfile/missing_flag_from_dnf_install
dnf package versions are not pinned dockerfile/missing_version_specification_in_dnf_install
Gem package versions are not pinned dockerfile/gem_install_without_version
Base image uses the latest tag dockerfile/image_version_using_latest
npm package versions are not pinned dockerfile/npm_install_without_pinned_version
Review pip caches included in container images dockerfile/pip_install_keeping_cached_packages
pip package versions are not pinned dockerfile/unpinned_package_version_in_pip_install
Review separate package-index refresh and installation dockerfile/update_instruction_alone
Review overlapping use of wget and curl dockerfile/run_using_wget_and_curl
Review yum installation cache cleanup dockerfile/yum_clean_all_missing
Review yum installation prompts dockerfile/yum_install_allows_manual_input
yum package versions are not pinned dockerfile/yum_install_without_version
Missing zypper non-interactive option dockerfile/missing_zypper_non_interactive_switch
Review zypper cache cleanup dockerfile/missing_zypper_clean
zypper package versions are not pinned dockerfile/zypper_install_without_version
Review Dockerfile layers and temporary files dockerfile/multiple_run_add_copy_instructions_listed
Dockerfile ends with root as the selected user dockerfile/last_user_is_root
Base-image version is not specified dockerfile/image_version_not_explicit
Review diagnostic commands in RUN dockerfile/run_utilities_and_posix_commands
Duplicate build-stage names dockerfile/same_alias_in_different_froms
Multiple CMD instructions in one build stage dockerfile/multiple_cmd_instructions_listed
Multiple ENTRYPOINT instructions in one build stage dockerfile/multiple_entrypoint_instructions_listed
Invalid COPY destination for multiple sources dockerfile/copy_with_more_than_two_arguments_not_ending_with_slash
Review integrity checks for remote artifacts dockerfile/curl_or_wget_instead_of_add
Review the range of EXPOSE port numbers dockerfile/unix_ports_out_of_range
Build stage referenced by number dockerfile/using_unnamed_build_stages
Review relative WORKDIR paths dockerfile/workdir_path_not_absolute
Pipeline without pipefail dockerfile/shell_running_a_pipe_without_pipefail_flag

Related pages48

Use COPY instead of ADD

Use COPY for local files and verify remote artifacts separately.

CMD and ENTRYPOINT without JSON form

Specify CMD and ENTRYPOINT arguments clearly and verify termination-signal handling.

Review COPY file ownership and write permissions

Grant the runtime account only necessary data-write permissions and protect application code.

COPY --from references its own build stage

Remove self-references from COPY --from build dependencies.

Review the intent of FROM platform selection

Align each build stage’s platform with the intended target.

Review container health-check configuration

Check service health as well as whether its process is running.

Use of the MAINTAINER instruction

Replace the deprecated MAINTAINER instruction with LABEL for image metadata.

Working directory set with RUN cd

Declare a working directory with WORKDIR when later instructions need it.

Review apt use in Dockerfile automation

Use apt-get and apt-cache for automated commands.

Using sudo in RUN

Make the RUN user explicit and remove unnecessary sudo use.

Changing the default shell with RUN

Use the SHELL instruction to explicitly select the Dockerfile’s default shell.

Review the container SSH port declaration

Declare only required service ports and separately restrict actual port publishing and SSH access.

Dockerfile has no USER instruction

Check the final image’s default user and run the application with only the privileges it needs.

Review apk installation cache management

Choose an installation approach that keeps unnecessary apk caches out of the final image.

apk package versions are not pinned

Leaving apk add package versions unspecified can change Docker build results.

Missing package version pins in apt-get installs

Specify package versions for apt-get install to reduce unexpected changes to build results while continuing to manage security updates.

Review apt-get installation prompts

Automate apt-get confirmation and check for additional package-specific input.

Review apt-get recommended package installation

Identify required packages and dependencies, and reduce unnecessary recommended packages.

Review apt-get package-list cleanup

Install packages and remove their package lists in the same RUN instruction.

Review dnf installation cache cleanup

Install packages and clean the dnf cache in the same RUN instruction.

Review dnf installation prompts

Automate dnf confirmation and test that builds complete without input.

dnf package versions are not pinned

Leaving versions unspecified in dnf install can change Docker build results.

Gem package versions are not pinned

Installing gems without versions can change the packages included in a Docker build.

Base image uses the latest tag

Using the latest tag can select a different base image in later Docker builds.

npm package versions are not pinned

Installing npm packages without pinned versions can change Docker build results.

Review pip caches included in container images

Keep unnecessary pip caches out of the final image.

pip package versions are not pinned

Installing Python packages without versions can change the libraries included in a Docker build.

Review separate package-index refresh and installation

Refresh package indexes and install packages in the same RUN.

Review overlapping use of wget and curl

Use one download tool when it meets the same requirements.

Review yum installation cache cleanup

Install packages and clean the yum cache in the same RUN.

Review yum installation prompts

Automate yum confirmation and verify that builds need no additional input.

yum package versions are not pinned

Installing yum packages without versions can change the contents of a Docker build.

Missing zypper non-interactive option

Handle zypper confirmation prompts and check automated build results.

Review zypper cache cleanup

Complete installation and zypper cache cleanup in the same RUN.

zypper package versions are not pinned

Specify reviewed package versions and maintain a security-update plan.

Review Dockerfile layers and temporary files

Combine installation and temporary-file cleanup where useful while preserving effective build caching.

Dockerfile ends with root as the selected user

After completing build steps that require root, set a non-root default user for the application.

Base-image version is not specified

An unspecified base-image version can change the result of a Docker build.

Review diagnostic commands in RUN

Run commands needed by the build and perform interactive diagnostics separately.

Duplicate build-stage names

Use a unique name for each FROM stage.

Multiple CMD instructions in one build stage

Make the intended default command explicit for each build stage.

Multiple ENTRYPOINT instructions in one build stage

Make each stage’s effective entrypoint and default arguments explicit.

Invalid COPY destination for multiple sources

End the destination directory path with / when copying multiple files.

Review integrity checks for remote artifacts

Verify remote files with a trusted checksum or signature before using them.

Review the range of EXPOSE port numbers

Declare valid port numbers that match the service’s actual listeners.

Build stage referenced by number

Use a descriptive stage name in COPY --from.

Review relative WORKDIR paths

Establish an explicit absolute working-directory path.

Pipeline without pipefail

Configure the shell to detect failures earlier in a pipeline.