This guide provides a comprehensive overview of the commonly used Dockerfile instructions with examples to help you create efficient and optimized Docker images.

1. FROM

Specifies the base image for the Docker image.

FROM ubuntu:latest

• Always the first instruction in a Dockerfile.

• Example: FROM python:3.9 for Python-based projects.

2. WORKDIR

Sets the working directory inside the container.

WORKDIR /app

• Ensures subsequent commands (like COPY or RUN) operate in this directory.

3. COPY

Copies files or directories from the build context into the container.

COPY src/ /app/

• Use COPY for local files.

• It's simpler and faster than ADD when no archive extraction or URL downloads are required.

4. ADD

Copies files or downloads remote resources. Also extracts archives.

ADD myfile.tar.gz /app/

• Automatically extracts compressed files (e.g., .tar.gz).

• Supports downloading files from remote URLs.

5. RUN

Executes commands during the build process (e.g., installing software).

RUN apt-get update && apt-get install -y curl

• Each RUN instruction creates a new image layer.

• Combine commands with && to minimize layers.

6. CMD

Specifies the default command to run when the container starts.

CMD ["python", "app.py"]

• Can be overridden at runtime using docker run <image> <command>.

7. ENTRYPOINT

Defines the main application or command to run in the container.

ENTRYPOINT ["nginx", "-g", "daemon off;"]

• Works with CMD to provide default arguments.

• Use ENTRYPOINT for containers meant to act like executables.

8. ENV

Sets environment variables.

ENV NODE_ENV=production

• Variables can be accessed inside the container.

9. EXPOSE

Documents the port(s) the container listens on.

EXPOSE 8080

• Does not publish the port; you need -p in docker run.

10. LABEL

Adds metadata to the image.

LABEL maintainer="you@example.com"

• Use for descriptions, versioning, or maintainers.

11. ARG

Defines build-time variables.

ARG APP_VERSION=1.0

• Passed during the build process (docker build --build-arg APP_VERSION=2.0).

12. VOLUME

Creates a mount point for persistent data.

VOLUME /data

• Ensures the directory persists outside the container.

13. USER

Specifies the user for running container processes.

USER appuser

• Use to improve security by avoiding root privileges.

14. SHELL

Changes the shell used in RUN commands.

SHELL ["/bin/bash", "-c"]

15. ONBUILD

Sets triggers for dependent images.

ONBUILD RUN apt-get update

• Executes only when the image is used as a base for another Dockerfile.

Best Practices

• Use Multi-Stage Builds: Reduce image size by separating build and runtime stages.

• Minimize Layers: Combine commands in RUN instructions.

• Leverage .dockerignore: Exclude unnecessary files from the build context.

• Use Tags for Base Images: Avoid latest for more consistent builds.

Example Dockerfile

Here's a complete example:

# Use Python as the base image
FROM python:3.9

# Set environment variables
ENV APP_HOME=/app

# Set the working directory
WORKDIR $APP_HOME

# Copy application files
COPY . $APP_HOME

# Install dependencies
RUN pip install -r requirements.txt

# Expose the port
EXPOSE 5000

# Run the application
CMD ["python", "app.py"]

Resources

• Dockerfile Reference

• Docker Best Practices