Common Dockerfile Instructions (FROM, RUN, COPY, ADD, CMD, ENTRYPOINT)

In containerized development with Docker, the Dockerfile is a core script that defines image build steps. It instructs Docker on how to construct the final runtime environment starting from a base image through a series of simple instructions. Understanding and correctly using key instructions such as FROM, RUN, COPY, ADD, CMD, and ENTRYPOINT is crucial for writing efficient, secure, and maintainable container images. This article provides an in-depth analysis of the functional characteristics and best practices for these commonly used instructions.

FROM: The Starting Point of Build Process

The FROM instruction must be the first line in a Dockerfile (unless using multi-stage builds) as it specifies the source base image. The Docker engine will start from this base image to execute all subsequent instructions, creating new immutable layers for the resulting image. Choosing an appropriate base image directly impacts the final image size, startup speed, and security posture.

  • Prefer Official Images: For common language runtimes or operating systems, always prioritize official FROM tags (e.g., python:3.9-slim, node:18-alpine) to ensure compatibility and stability.
  • Pin Specific Versions: Always specify a specific version number rather than relying solely on the latest tag (latest). This prevents built images from depending on future, uncertain software package updates and ensures environmental consistency.

RUN and Command Execution Sequences

The RUN instruction is used to execute shell or command-line operations during the build process. It can be a single line or multi-line Shell statement and may include subshell scripts. Each layer generated by this instruction becomes an immutable read-only layer in the new image.

  • Multi-stage Optimization: Connecting multiple commands with && saves space and enhances security. For example, install development tools to build the project first, then clean up unnecessary files, and finally copy artifacts into the base runtime environment:
    RUN apt-get update && \
    apt-get install -y gcc make curl && \
    rm -rf /var/lib/apt/lists/*
  • Avoid Interactive Commands: In production builds, avoid using commands that require user interaction (such as input or waiting for input), which can cause the build process to hang.

COPY and ADD File Transfer Mechanisms

When content from the local filesystem needs to be copied into an image, you must choose between COPY or ADD. While both share similar functionality, they exhibit significant behavioral differences.

  • COPY: Secure and Controllable
    • COPY copies files only from specified paths to a target directory within the container. It does not automatically extract archive files (such as .tar, .zip) nor download resources from remote URLs. This determinism makes the build process easier to debug and version control, making it the preferred choice for production environments.
  • ADD: Convenient but Risky
    • In addition to COPY functionality, ADD can automatically extract archive files (like tar, gzip) and supports downloading resources from URLs via the -U parameter. However, this "smart" feature may lead to unpredictable build behaviors; for instance, it might inadvertently modify source files or introduce unnecessary dependency layers.

CMD: Defining Container Start Command

The CMD instruction specifies the default command and arguments that run inside a container. If users do not provide -c (or --cmd) options during docker run, Docker will execute this command; if provided, it overrides the content of CMD. It is commonly used to expose the primary entry point for an application.

  • Flexibility: Suitable for defining default behavior while allowing fine-tuning via command-line arguments:
    CMD ["nginx", "-g", "daemon off;"]
  • Application in Multi-stage Builds: In second-stage builds, CMD is typically used to launch the final application instance.

ENTRYPOINT vs CMD: Command Execution Priority

Although both ENTRYPOINT and CMD define entry points, their behavior during Docker execution differs significantly; understanding this distinction is crucial for writing complex container orchestration scripts.

  • ENTRYPOINT

    • Acts as the "main program" or script runner of a container with high rigidity. It defines the first command executed when the container starts.
    • Arguments provided in docker run are appended after commands specified by ENTRYPOINT (unless overridden via -e). This makes ENTRYPOINT ideal for defining immutable core logic, such as /bin/bash -c "..." or specific daemon startup scripts:

  • CMD

    • Runs as supplementary arguments to ENTRYPOINT. If no ENTRYPOINT is set, CMD executes. If both are set, ENTRYPOINT takes precedence with CMD appended (acting as additional parameters):
      ENTRYPOINT ["/usr/local/bin/myapp"]
CMD ["--mode", "production"]

Comprehensive Example and Best Practices Summary

To clearly demonstrate the synergistic effect of these instructions, here is a simplified Dockerfile snippet for building a web application. This example illustrates how to combine the above instructions to create a lightweight, secure image:

# 1. Define base environment (FROM)
FROM node:18-alpine

# 2. Install system dependencies and clean cache (RUN + RUN)
RUN apk add --no-cache curl python3 make g++

# 3. Copy project files into the container image (COPY)
WORKDIR /app
COPY package*.json ./
COPY . .

# 4. Build application (RUN)
RUN npm ci && npm run build

# 5. Define default start command and entry point (CMD + ENTRYPOINT)
ENTRYPOINT ["node"]
CMD ["/dist/app.js"]

By adhering to the guidelines outlined above, developers can ensure that Dockerfiles are not only functionally complete but also optimized for performance, security, and maintainability. In real-world projects, it is advisable to avoid mixing overly complex logic within a single instruction; maintaining the principle of keeping each layer clear and explicit aids team collaboration and subsequent image optimization efforts.