Dockerfiles

Chapter 05: Dockerfiles

Dockerfiles are text files containing instructions to build Docker images. This chapter covers writing effective Dockerfiles.

Dockerfile Basics

A Dockerfile is a script with instructions to build an image:

# Comment
FROM ubuntu:20.04
LABEL maintainer="you@example.com"
RUN apt-get update && apt-get install -y nginx
COPY index.html /var/www/html/
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Dockerfile Instructions

FROM

Sets the base image:

# Use official base image
FROM node:18-alpine
FROM python:3.11-slim

# Use specific version
FROM nginx:1.25

# Multi-stage build - first stage
FROM node:18 AS builder

LABEL

Add metadata to the image:

LABEL version="1.0"
LABEL description="My web application"
LABEL maintainer="you@example.com"
LABEL "org.opencontainers.image.authors"="you@example.com"

RUN

Execute commands during build:

# Shell form
RUN apt-get update && apt-get install -y nginx

# Exec form (preferred)
RUN ["apt-get", "update"]
RUN ["apt-get", "install", "-y", "nginx"]

COPY

Copy files from build context to image:

# Copy single file
COPY index.html /var/www/html/

# Copy directory
COPY src/ /var/www/html/src/

# Copy with ownership
COPY --chown=www-data:www-data . /var/www/html/

ADD

Similar to COPY but with additional features:

# Copy and extract tar files
ADD website.tar.gz /var/www/html/

# Copy from URL
ADD https://example.com/file.tar.gz /tmp/

Best Practice: Use COPY unless you need ADD’s features.

WORKDIR

Set the working directory:

WORKDIR /app
WORKDIR /var/log
WORKDIR /workspace

ENV

Set environment variables:

ENV NODE_ENV=production
ENV PORT=8080
ENV DATABASE_URL=postgres://user:pass@db:5432/mydb

EXPOSE

Document which ports the container listens on:

EXPOSE 80
EXPOSE 443
EXPOSE 8080 8081 8082

USER

Set the user for subsequent commands:

# Create user
RUN addgroup -g 1000 appgroup && adduser -u 1000 -G appgroup -s /bin/sh -D appuser

# Switch to user
USER appuser

ARG

Define build-time variables:

ARG VERSION=latest
ARG BUILD_DATE

# Use ARG
RUN echo "Building version $VERSION"

ENTRYPOINT

Configure the command that always executes:

# Exec form
ENTRYPOINT ["python", "app.py"]

# Shell form
ENTRYPOINT python app.py

CMD

Define the default command:

# Exec form (preferred)
CMD ["nginx", "-g", "daemon off;"]

# Shell form
CMD nginx -g "daemon off;"

# Default arguments for ENTRYPOINT
CMD ["--port", "8080"]

Dockerfile Best Practices

1. Use Specific Base Images

# Bad
FROM ubuntu

# Good
FROM ubuntu:20.04

# Better - Alpine based
FROM node:18-alpine

2. Use .dockerignore

.git
node_modules
npm-debug.log
.env
*.md
__pycache__
*.pyc
.vscode
.idea

3. Order Instructions for Caching

# Bad - invalidates cache for every code change
COPY . .
RUN npm install
FROM node:18

# Good - cache npm install unless package.json changes
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .

4. Use Multi-stage Builds

# Build stage
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Production stage
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

5. Minimize Layers

# Bad - multiple RUN layers
RUN apt-get update
RUN apt-get install -y nginx
RUN apt-get clean
RUN rm -rf /var/lib/apt/lists/*

# Good - single RUN layer
RUN apt-get update && \
    apt-get install -y nginx && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

6. Don’t Run as Root

# Create non-root user
RUN addgroup -g 1000 appgroup && \
    adduser -u 1000 -G appgroup -s /bin/sh -D appuser

# Set ownership
RUN chown -R appuser:appgroup /app

USER appuser

7. Use Health Checks

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

8. Use Labels for Metadata

LABEL maintainer="you@example.com"
LABEL version="1.0.0"
LABEL description="My application"

Dockerfile Examples

Node.js Application

# Build stage
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# Production stage
FROM node:18-alpine
WORKDIR /app
RUN addgroup -g 1000 -S nodejs && \
    adduser -u 1000 -S nodejs -G nodejs
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
USER nodejs
EXPOSE 3000
CMD ["node", "dist/index.js"]

Python Application

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY . .

# Create non-root user
RUN useradd -m -u 1000 appuser && \
    chown -R appuser:appuser /app
USER appuser

EXPOSE 8000
CMD ["python", "main.py"]

Go Application

# Build stage
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main .

# Production stage
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /app
COPY --from=builder /app/main .
EXPOSE 8080
CMD ["./main"]

Building Images

# Build with default tag
docker build .

# Build with custom tag
docker build -t myapp:latest .

# Build with build args
docker build --build-arg VERSION=1.0 -t myapp:1.0 .

# Build with no cache
docker build --no-cache -t myapp:latest .

# Build with target stage (multi-stage)
docker build --target builder -t myapp:builder .

# Build and pass secrets (for RUN --mount=type=cache)
docker build --secret id=npm,src=.npmrc -t myapp .

Dockerfile Validation

# Lint Dockerfile
docker build --check .

# Hadolint (external tool)
hadolint Dockerfile

Dockerfile Syntax Highlighting

Most editors support Dockerfile syntax highlighting:

VS Code: Docker extension
IntelliJ: Docker plugin
Sublime: Dockerfile syntax

Summary

In this chapter, you learned:

Dockerfile instructions (FROM, RUN, COPY, etc.)
Best practices for writing efficient Dockerfiles
Multi-stage builds
Security best practices
Building images from Dockerfiles