Dockerfile Masterclass: Learn Every Dockerfile Instruction

1. Why Do We Need Dockerfiles? (The Problem Statement)

In containerization, containers must be reproducible, portable, and automated. While you can manually start a base container (such as Ubuntu) and execute commands interactively (apt install, mkdir, etc.), doing so is non-repeatable, prone to human error, and impossible to scale cleanly in CI/CD pipelines.

A Dockerfile serves as the programmatic blueprint or recipe to assemble a Docker image. Each line in a Dockerfile represents an instruction that executes sequentially, adding a discrete read-only file layer to the final image.

2. Core Mental Model: The Layered Architecture

Every time you add an instruction to a Dockerfile, Docker creates an intermediate layer and utilizes a build cache. Understanding this layer caching mechanism is critical for performance and image sizing.

Real-Life Analogy: The Layered Baking Recipe

Think of a Dockerfile like baking a multi-layered cake from scratch. Layer 1 is baking the base sponge cake (FROM ubuntu). Layer 2 is spreading the strawberry filling (RUN apt update). Layer 3 is adding frosting (RUN apt install nginx).

If you change Layer 2 (the filling), you don't need to rebake Layer 1 (the base sponge); Docker reuses the cached base layer and only rebuilds from Layer 2 onward. However, if you change an early layer, all subsequent cached layers are invalidated and must be rebuilt.

3. Step-by-Step Evolution of a Dockerfile

Let's build a production-ready Dockerfile step-by-step, observing how image sizes and layers evolve.

Step 3.1: Defining the Base Image (FROM)

The FROM instruction initializes a new build stage and sets the Base Image for subsequent instructions. Every valid Dockerfile must start with a FROM directive.

# Define the base image for our application
FROM ubuntu:latest

• Image Size Baseline: Starting with ubuntu:latest yields an initial image size of approximately 101 MB.

Step 3.2: Executing Shell Commands (RUN)

The RUN instruction executes any commands on top of the current image in a new layer and commits the results.

# Update package lists and install Nginx web server
RUN apt update
RUN apt install -y nginx

• Impact on Image Size:
  • After apt update: Size increases to 167 MB.
  • After apt install -y nginx: Size increases to 174 MB.
• Verifying Container State Without Interactive Shell: Instead of executing docker exec -it <container_id> bash to inspect container details, you can run diagnostic commands directly:
  BASH

  Copy

  # Check Nginx version
  docker run app nginx -version
  
  # Validate underlying OS version
  docker run app cat /etc/os-release
  

Step 3.3: Setting the Working Directory (WORKDIR)

By default, commands execute in the root directory (/). Operating in / is dangerous and a bad practice. The WORKDIR instruction sets the working directory for any RUN, CMD, ENTRYPOINT, COPY, or ADD instruction that follows it.

# Set the working directory for subsequent instructions
WORKDIR /app

• Verification: Running docker run app pwd now outputs /app instead of /.

Step 3.4: Copying Local Files (COPY)

The COPY instruction copies new files or directories from your local host machine and adds them to the filesystem of the container at the specified destination.

# Copy local HTML files into the container's working directory (/app)
COPY index.html /app/
COPY admin.html .

Note: Using . as the destination when WORKDIR is set to /app is functionally identical to specifying absolute paths like /app. Both successfully map host files into the container's working directory.

Step 3.5: Adding Files and Remote URLs (ADD)

The ADD instruction is similar to COPY, but it includes extra capabilities: it can automatically extract local tar archive files, and it can fetch remote URLs.

# Add files or fetch remote repositories/URLs
ADD https://github.com/username/repo.git /app/

Important Technical Note: When pulling from a remote Git repository, ensure you supply the exact remote path ending with .git so Docker can properly clone and integrate the repository contents into the image layer.

Step 3.6: Managing Users and Permissions (USER)

By default, Docker containers run commands and processes as the root user, presenting a major security vulnerability. The USER instruction sets the user name (or UID) and optionally the user group (or GID) to use when running the image and for any subsequent instructions (RUN, CMD, ENTRYPOINT).

# Create a dedicated non-root user and group
RUN useradd -g sudo delta

# Change ownership of /app to the new user so they have write permissions
RUN chown -R delta:delta /app

# Switch to the non-root user for subsequent operations
USER delta

• Verification: Running docker run app whoami will now return delta instead of root.

Step 3.7: Environment Variables (ENV)

The ENV instruction sets environment variables that persist during the container's execution and can be referenced by applications running inside.

# Define environment variables
ENV environment=production

• Verification: Running docker run app printenv will list all active environment variables, including environment=production.

Step 3.8: Adding Metadata (LABEL)

The LABEL instruction adds metadata (key-value pairs) to a Docker image, useful for organization, licensing, and author attribution.

# Add maintainer and metadata tags
LABEL maintainer="Shubham Gaur"

4. Comprehensive Dockerfile Instruction Reference Table

5. Real-World Pitfalls & Debugging Mindset

1. Layer Bloat & Image Size Inflation:

   • Problem: Adding too many independent RUN statements (e.g., separate RUN apt update, RUN apt install, RUN apt clean) creates excessive intermediate layers, inflating image size.
   • Solution: Combine commands into a single chained RUN statement using && and clean up package caches in the same layer.
     DOCKERFILE

     Copy

     RUN apt update && apt install -y nginx && rm -rf /var/lib/apt/lists/*
     

2. Root User Security Risks:

   • Problem: Running applications as root allows malicious actors who breach the application to gain full control of the underlying host container environment.
   • Solution: Always create a non-root system user using useradd, adjust directory ownership with chown, and switch context using USER.

3. Cache Invalidation Failures:

   • Problem: Changing a file high up in your Dockerfile (like COPY package.json) invalidates the cache for all subsequent layers, forcing expensive reinstalls.
   • Solution: Copy dependency definition files first, run package installs, and only then copy application source code.

6. Complete Assembled Dockerfile Example

Putting all the masterclass principles together, a clean, structured, and secure production Dockerfile looks like this:

# 1. Base Image Setup
FROM ubuntu:latest

# 2. Add Metadata
LABEL maintainer="Shubham Gaur"

# 3. Set Working Directory
WORKDIR /app

# 4. System Updates and Package Installations
RUN apt update && \
    apt install -y nginx && \
    rm -rf /var/lib/apt/lists/*

# 5. Environment Configuration
ENV environment=production

# 6. Create Non-Root User and Assign Permissions
RUN useradd -g sudo delta && \
    chown -R delta:delta /app

# 7. Switch to Secure User Context
USER delta

# 8. Copy Application Assets
COPY index.html admin.html /app/

# 9. Expose Port and Define Default Command
EXPOSE 8080
CMD ["nginx", "-g", "daemon off;"]

7. Summary and Key Takeaways

• Dockerfiles as Blueprints: Dockerfiles automate the reproducible creation of lightweight, containerized environments through ordered instruction lines.
• Layer-Based Architecture: Every instruction creates an immutable file layer and utilizes a build cache to accelerate subsequent builds.
• The FROM Foundation: Every valid Dockerfile must start with a FROM directive defining the base runtime or OS image.
• RUN vs CMD: RUN executes commands at build time to construct the image, while CMD specifies default commands executed at container runtime.
• Directory Management with WORKDIR: Always define a working directory (WORKDIR /app) to avoid executing operations in root (/).
• COPY vs ADD: Use COPY for standard local file transfers; use ADD when handling remote Git repositories or auto-extracting archives.
• Security Best Practices: Avoid running containers as the root user by explicitly creating restricted users via useradd and enforcing permissions with chown.
• Environment and Metadata: Use ENV for application configuration variables and LABEL for clean image documentation.