Built files by developers, for developers.

---

Dockerfile Basics

This repository explains the fundamental instructions used inside a Dockerfile and how they contribute to building a container image.

The goal is to understand how Docker constructs images layer by layer and how each instruction affects the final result. This repository focuses strictly on core concepts and avoids advanced optimizations.

📌 Table of Contents

• Overview
• What is a Dockerfile
• How Image Layers Work
• FROM
• WORKDIR
• COPY
• RUN
• CMD
• Building the Image
• Key Concepts

---

Overview

A Dockerfile is a declarative file that defines how a Docker image is built. Each instruction inside a Dockerfile creates a new immutable layer on top of the previous one. Understanding these instructions is essential because every container starts from an image, and every image is built from a Dockerfile.

What is a Dockerfile

A Dockerfile is a plain text file that contains a sequence of instructions. Docker reads this file from top to bottom during the build process.

Each instruction:

• Executes in order
• Creates a new image layer
• Modifies the filesystem or metadata of the image

Basic structure example:

FROM alpine:latest
WORKDIR /app
COPY . .
RUN apk add --no-cache curl
CMD ["sh"]

How Image Layers Work

Docker images are built as a stack of read-only layers.

Each instruction in a Dockerfile creates a new layer:

• FROM creates the base layer.
• COPY adds files as a new layer.
• RUN creates a layer with filesystem changes.
• CMD defines metadata for container startup.

Layers are cached. If nothing changes in a step, Docker reuses the cached layer instead of rebuilding it. This layer model makes builds efficient and reproducible.

FROM

The FROM instruction defines the base image. It must be the first instruction in a Dockerfile.

Example:

FROM alpine:3.19

This tells Docker to start building the image from the official Alpine Linux image. You can also use more complete base images:

FROM node:20-alpine

Without FROM, Docker does not know what environment to start from.

WORKDIR

The WORKDIR instruction sets the working directory inside the image. If the directory does not exist, Docker creates it.

Example:

WORKDIR /app

All subsequent instructions such as COPY, RUN, and CMD will execute relative to this directory. This avoids repeatedly writing absolute paths.

COPY

The COPY instruction copies files from your local machine into the image.

Example:

COPY . .

This copies everything from the current directory (build context) into the current WORKDIR inside the image.

More explicit example:

COPY package.json /app/

This copies a specific file into a specific location.

Important concept:

• Docker can only copy files that are inside the build context (the directory where you run docker build).

RUN

The RUN instruction executes commands during the image build process. It modifies the image filesystem and creates a new layer.

Example:

RUN apk add --no-cache curl

This installs curl inside the image. Another example:

RUN npm install

This installs application dependencies.

Important distinction:

• RUN executes at build time.
• It does not run when the container starts.
• It changes the image itself.

CMD

The CMD instruction defines the default command that runs when a container starts. It does not execute during build.

Example:

CMD ["node", "app.js"]

This means when someone runs:

docker run my-image

Docker will execute:

node app.js

If the user provides a command at runtime, it overrides CMD. CMD defines runtime behavior, not build behavior.

Building the Image

To build an image from a Dockerfile:

docker build -t my-image .

Explanation:

• t my-image assigns a name (tag) to the image.
• .defines the build context (current directory).

Docker will:

1. Read the Dockerfile.
2. Execute each instruction in order.
3. Create layers.
4. Produce a final image.

You can verify the image:

docker images

key Concepts

• A Dockerfile defines how an image is built.
• Each instruction creates a new immutable layer.
• FROM defines the base image.
• WORKDIR sets the working directory.
• COPY adds files into the image.
• RUN executes commands during build.
• CMD defines what runs when the container starts.
• Image layers are cached for performance.
• Containers are runtime instances of images built from Dockerfiles.