What Is a Dockerfile? Guide, Syntax, Examples & Best Practices

A Dockerfile is the foundation of modern containerization, enabling developers to define, build, and manage container images with precision and repeatability. Whether you’re new to Docker or looking to improve your workflows, understanding Dockerfiles is essential for efficient cloud infrastructure management and seamless application deployment using the Docker engine.

Why Use a Dockerfile?

A Dockerfile is a plain text file named Dockerfile that contains a series of Dockerfile instructions for building a Docker image. This approach offers several benefits:

• Automation: Eliminates manual steps by scripting the image creation process using Docker CLI commands and build command patterns.
• Consistency: Ensures every environment (development, staging, production) runs the same application stack with the same environment variables set.
• Reproducibility: Version control your Dockerfile alongside your source code for easy rollbacks and audits.
• Portability: Run your application anywhere Docker is supported, from local machines to production clusters using the docker run command.

By leveraging Dockerfiles, teams can accelerate cloud migration, streamline DevOps automation, and maintain better cloud compliance.

Basic Structure and Syntax of a Dockerfile

Dockerfile Syntax Overview

A Dockerfile uses a simple, readable Dockerfile syntax:

# Comment
INSTRUCTION arguments

• Instructions are typically written in uppercase (e.g., FROM, RUN, COPY).
• Each line represents a build step in the build process, processed from top to bottom.
• Comments start with # and are ignored during the build.

Common Instructions

• FROM: Sets the base image such as an operating system or language runtime.
• RUN: Executes a run command such as apt-get update during the build.
• COPY / ADD: Transfers files from the local build context or remote locations.
• CMD / ENTRYPOINT: Specifies the default command or entrypoint command.
• ENV: Set environment variables using the env instruction.
• WORKDIR: Changes the working directory for subsequent instructions.
• EXPOSE: Documents the exposed ports.
• USER: Sets the uid user or non root user.
• ARG, LABEL, VOLUME, ONBUILD: Advanced configuration for build time variables, metadata, and triggers.

Comments and Formatting

Use comments and echo command logs to document your Dockerfile, making it easier to trace issues across multiple lines of the file.

Key Dockerfile Instructions Explained

FROM

The following command specifies the base image for your container image build:

FROM ubuntu:22.04

RUN

Executes shell commands during the build process:

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

COPY and ADD

• COPY: Copy files and directories from your project.
• ADD: Like COPY but also handles remote files and archives.

COPY app.py /app/app.py
ADD https://example.com/config.tar.gz /app/config/

ENV

Set environment variables:

ENV NODE_ENV=production

CMD vs ENTRYPOINT

• CMD command: Default arguments for the container.
• ENTRYPOINT command: Defines the executable.

ENTRYPOINT ["python3"]
CMD ["app.py"]

WORKDIR

Sets the working directory:

WORKDIR /app

EXPOSE

Documents the container’s network ports:

EXPOSE 8080

USER

Specifies which uid user will run subsequent instructions:

USER appuser

Other Instructions

• ARG: Build time variables.
• LABEL: Metadata.
• VOLUME: Persistent storage mount points.
• ONBUILD: Triggers for child images.

Step-by-Step Example: Creating and Using a Dockerfile

Sample Application Code

Create a new file named main.js:

console.log("Hello, Docker!");

Writing the Dockerfile

Create a file named Dockerfile with these Docker file instructions:

FROM node:18
WORKDIR /app
COPY main.js .
CMD ["node", "main.js"]

Building the Docker Image

Use the Docker build command in your command line:

docker build -t hello-docker .

Running the Container

Use this run instruction:

docker run hello-docker

You should see output in your terminal:

Hello, Docker!

For more advanced setups involving multiple containers, check out our Laravel Docker Ubuntu guide.

Dockerfile Best Practices

• Use Trusted Base Images: Start from official sources on Docker Hub.
• Minimize Image Size and Layers: Combine commands and clean up unneeded files and directories to reduce image layer size.
• Avoid Hardcoding Secrets: Use environment variables or secret management.
• Use .dockerignore: Exclude irrelevant files from the build context (e.g., node_modules, .git).
• Set Proper ENTRYPOINT and CMD: Clearly define the container’s startup behavior with the default command.
• Add HEALTHCHECK: Monitor container health.
• Label Your Images: Use the LABEL instruction to enhance traceability.

Troubleshooting Dockerfile Issues

• Check Build Logs: For errors related to copy instructions or image built errors.
• Validate Syntax: Use linters and order dockerfile instructions logically.
• Optimize Layer Caching: Place volatile commands lower.
• Manage Dependencies: Ensure all the dependencies are included in the docker container using docker ps command.

Dockerfile vs Docker Compose

A Dockerfile defines how to build a single Docker container image. Docker Compose, using docker-compose.yml, is used to manage multiple containers such as a web server and database. It defines service relationships, networking, and shared configuration files.

For related topics, explore Kubernetes vs Docker and Docker Alternatives.

Frequently Asked Questions (FAQs) about Dockerfiles

What is a Dockerfile?

A Dockerfile is a script containing instructions for building a Docker image.

How do you create a Dockerfile?

Create a plain text file named Dockerfile in your current directory and add build instructions.

What are the most important Dockerfile instructions?

Common ones include FROM, RUN, COPY, CMD, ENTRYPOINT, ENV, WORKDIR, and EXPOSE.

What is the difference between CMD and ENTRYPOINT?

CMD sets default arguments, while ENTRYPOINT defines the executable.

How do I build a Docker image from a Dockerfile?

Use the command: docker build -t your-image-name .

What is the difference between Dockerfile and Docker Compose?

A Dockerfile builds images; Docker Compose manages multi-container setups.

What are best practices for writing Dockerfiles?

Use trusted images, minimize layers, avoid secrets, and use .dockerignore.

How do I troubleshoot Dockerfile build errors?

Check logs, validate syntax, and ensure all dependencies are available.

Can I use variables in Dockerfiles?

Yes, with ARG for build-time and ENV for runtime variables.

What is the purpose of the .dockerignore file?

It excludes files and directories from the build context, speeding up builds.

What is the difference between COPY and ADD in Dockerfile?

COPY is for local files; ADD supports URLs and auto-extracts archives.

Can I use multiple FROM instructions in a Dockerfile?

Yes, for multi-stage builds to optimize image size.

How do I keep my Docker images secure?

Use official images, scan for vulnerabilities, and avoid embedding secrets.

What is a multi-stage build in Dockerfile?

A way to use multiple FROM instructions to build and copy only necessary artifacts, reducing final image size.

How do I set environment variables in Dockerfile?

Use the ENV instruction.