Dockerfile Instructions
This lesson covers all major Dockerfile instructions, when to use them, and best practices for each.
Complete Instruction Reference
| Instruction | Purpose |
|---|---|
| FROM | Set base image |
| WORKDIR | Set working directory |
| COPY | Copy files from build context |
| ADD | Copy files with extra features |
| RUN | Execute build commands |
| CMD | Default container command |
| ENTRYPOINT | Configure container executable |
| ENV | Set environment variables |
| ARG | Define build arguments |
| EXPOSE | Document container ports |
| VOLUME | Create mount points |
| USER | Set user for commands |
| LABEL | Add metadata |
| HEALTHCHECK | Define health check |
FROM
Initializes a new build stage and sets the base image:
# Basic usage
FROM ubuntu:22.04
# With platform specification
FROM --platform=linux/amd64 node:18
# Named build stage (for multi-stage builds)
FROM node:18 AS builder
# Using digest for exact version
FROM nginx@sha256:abc123...
Base Image Selection
# Full OS - largest, most compatible
FROM ubuntu:22.04 # ~77MB
# Slim variants - smaller
FROM python:3.11-slim # ~125MB vs ~1GB for full
# Alpine - smallest but different libc
FROM node:18-alpine # ~175MB vs ~1GB for full
# Distroless - minimal, secure
FROM gcr.io/distroless/base # Only runtime dependencies
# Scratch - empty, for static binaries
FROM scratch
ENV
Sets environment variables available during build and runtime:
# Single variable
ENV NODE_ENV=production
# Multiple variables (preferred syntax)
ENV NODE_ENV=production \
PORT=3000 \
LOG_LEVEL=info
# Old syntax (still works)
ENV NODE_ENV production
Variables can be used later:
ENV APP_DIR=/app
WORKDIR $APP_DIR
COPY . $APP_DIR
ARG
Defines variables for build-time only:
# Define argument with default value
ARG NODE_VERSION=18
FROM node:${NODE_VERSION}
# ARG without default (must be provided)
ARG BUILD_DATE
# Use in build commands
ARG VERSION
RUN echo "Building version ${VERSION}"
# ARG after FROM only available in that stage
FROM node:18
ARG APP_VERSION
LABEL version=${APP_VERSION}
Pass arguments during build:
docker build --build-arg VERSION=1.0.0 --build-arg BUILD_DATE=$(date -u +%Y%m%d) -t myapp .
ARG vs ENV
| Feature | ARG | ENV |
|---|---|---|
| Available during build | Yes | Yes |
| Available at runtime | No | Yes |
| Persists in image | No | Yes |
| Can be overridden | At build time | At run time |
COPY vs ADD
COPY (Preferred)
Simple, predictable file copying:
# Copy file
COPY app.js .
# Copy multiple files
COPY package.json package-lock.json ./
# Copy directory contents
COPY src/ ./src/
# Copy with different name
COPY app.js application.js
# Set ownership
COPY --chown=node:node . .
# From a build stage
COPY --from=builder /app/dist ./dist
ADD (Special cases only)
Extra features beyond COPY:
# Auto-extract tar archives
ADD archive.tar.gz /app/
# Download from URL (not recommended)
ADD https://example.com/file.tar.gz /app/
# Local tar extraction
ADD local-archive.tar /app/
Best Practice: Use COPY unless you need ADD's features.
RUN
Executes commands during build:
# Shell form - runs in /bin/sh -c
RUN apt-get update && apt-get install -y curl
# Exec form - direct execution
RUN ["pip", "install", "--no-cache-dir", "-r", "requirements.txt"]
# Best practice: combine related commands
RUN apt-get update \
&& apt-get install -y \
curl \
git \
vim \
&& rm -rf /var/lib/apt/lists/*
# Don't do this - creates large layers
RUN apt-get update
RUN apt-get install -y curl
RUN apt-get install -y git
CMD vs ENTRYPOINT
CMD
Provides defaults for container execution:
# Exec form (preferred)
CMD ["node", "app.js"]
# Shell form
CMD npm start
# As parameters to ENTRYPOINT
ENTRYPOINT ["python"]
CMD ["app.py"] # Default file, can be overridden
CMD can be overridden at runtime:
docker run myapp # Uses CMD
docker run myapp bash # Overrides CMD with bash
ENTRYPOINT
Configures the container as an executable:
# Exec form (preferred)
ENTRYPOINT ["python", "app.py"]
# Container always runs python app.py
# Arguments are appended
docker run myapp --debug # Runs: python app.py --debug
Combining ENTRYPOINT and CMD
# ENTRYPOINT = the executable
# CMD = default arguments
ENTRYPOINT ["python"]
CMD ["app.py"]
# docker run myapp → python app.py
# docker run myapp script.py → python script.py
USER
Sets the user for subsequent instructions and container runtime:
# Create user and switch to it
RUN groupadd -r appgroup && useradd -r -g appgroup appuser
USER appuser
# Or use existing user
USER node
# Can switch back to root if needed
USER root
RUN apt-get update
USER appuser
Best Practice: Don't run containers as root in production.
WORKDIR
Sets the working directory:
# Absolute path
WORKDIR /app
# Creates directory if it doesn't exist
WORKDIR /opt/myapp
# Relative paths build on previous WORKDIR
WORKDIR /app
WORKDIR src # Now in /app/src
WORKDIR ../lib # Now in /app/lib
EXPOSE
Documents the ports the container listens on:
# TCP port (default)
EXPOSE 3000
# Multiple ports
EXPOSE 80 443
# UDP port
EXPOSE 53/udp
# Both TCP and UDP
EXPOSE 53/tcp 53/udp
Remember: EXPOSE is documentation. Use -p to actually publish ports.
VOLUME
Creates a mount point for persistent data:
# Single volume
VOLUME /data
# Multiple volumes
VOLUME ["/data", "/logs"]
# Data will persist across container restarts
VOLUME /var/lib/mysql
LABEL
Adds metadata to the image:
LABEL maintainer="developer@example.com"
LABEL version="1.0"
LABEL description="My application"
# Multiple labels
LABEL maintainer="developer@example.com" \
version="1.0" \
org.opencontainers.image.source="https://github.com/user/repo"
View labels:
docker inspect --format='{{json .Config.Labels}}' myimage
HEALTHCHECK
Defines how Docker checks if the container is healthy:
# HTTP health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD curl -f http://localhost:3000/health || exit 1
# Simple process check
HEALTHCHECK CMD pgrep node || exit 1
# Disable health check from base image
HEALTHCHECK NONE
Options:
--interval: Time between checks (default: 30s)--timeout: Timeout for single check (default: 30s)--start-period: Grace period for startup (default: 0s)--retries: Failures before unhealthy (default: 3)
SHELL
Changes the default shell:
# Default is ["/bin/sh", "-c"]
SHELL ["/bin/bash", "-c"]
# Now RUN uses bash
RUN source ~/.bashrc && npm install
ONBUILD
Triggers instructions when image is used as a base:
# In base image
FROM node:18
ONBUILD COPY package*.json ./
ONBUILD RUN npm install
ONBUILD COPY . .
# When someone builds FROM this image,
# the ONBUILD instructions run automatically
Key Takeaways
- Use ENV for runtime configuration, ARG for build-time only
- Prefer COPY over ADD unless you need tar extraction
- Combine RUN commands to reduce layers
- Use ENTRYPOINT for the main executable, CMD for default arguments
- Always run containers as non-root users in production
- Use HEALTHCHECK to monitor container health
- Add LABELs for image metadata and documentation
التالي · الدرس 12 من 32
Building Custom Images
قراءة 5 دقيقة
أنهيت 11 من 32 درسًا

اسأل Byte عن هذا الدرس
محادثة خاصة حول هذا الدرس. قرأ Byte الدرس كاملًا، ويجيب خلال ثوانٍ، ويُظهر القسم الذي تأتي منه كل إجابة. يمكنك السؤال بأي لغة.
الأسئلة والأجوبة
أسئلة عامة حول هذا الدرس. يجيب AI Tutor فورًا بلغتك، ويراجع فريق FreeAcademy الإجابات، ويمكن لكل المتعلمين قراءتها.

