Dockerfile Best Practices

Best practices for writing efficient and secure Dockerfiles.

1. Use a Minimal Base Image

# Bad: Large image
FROM ubuntu:22.04

# Good: Minimal image
FROM node:18-alpine
FROM python:3.11-slim
FROM golang:1.21-alpine

2. Order Instructions Correctly

# Good: Copy dependencies first
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

# Bad: Copy everything then install
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm ci --only=production

3. Use Multi-Stage Builds

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

# Stage 2: Production
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

4. Reduce the Number of Layers

# Bad: Many layers
RUN apt-get update
RUN apt-get install -y curl
RUN apt-get install -y wget
RUN apt-get clean

# Good: Combine commands
RUN apt-get update && \
    apt-get install -y curl wget && \
    rm -rf /var/lib/apt/lists/*

5. Use .dockerignore

node_modules
npm-debug.log
.git
.gitignore
.env
.env.local
*.md
docker-compose*.yml
Dockerfile*
.dockerignore
coverage
.nyc_output

6. Don't Run as Root

# Create a non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Set the working directory
WORKDIR /app

# Copy files with the correct permissions
COPY --chown=nodejs:nodejs . .

# Run as non-root
USER nodejs

7. Use a Health Check

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

8. Use ARG for Build Time

ARG NODE_ENV=production
ENV NODE_ENV=$NODE_ENV

9. Copy Specific Files

# Bad
COPY . .

# Good
COPY package*.json ./
COPY src/ ./src/
COPY tsconfig.json ./

10. Use EXPOSE Correctly

# Declare the port
EXPOSE 3000

# But still use -p when running
# docker run -p 3000:3000 myapp

Use Case: Application Dockerfile

# Backend API - Production Ready
FROM node:18-alpine AS builder

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy source
COPY . .

# Build
RUN npm run build

# Stage 2: Production
FROM node:18-alpine

# Security: non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

WORKDIR /app

# Copy from the builder
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# Environment
ENV NODE_ENV=production
ENV PORT=3000

# Switch to non-root
USER nodejs

# Expose the port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# Run
CMD ["node", "dist/server.js"]

Everyday Use Case

Case: Build time is too long.

# Check the layers that changed
docker history myapp:latest

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

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

Checklist

[ ] Use a minimal base image (Alpine)
[ ] Order instructions correctly
[ ] Use multi-stage builds
[ ] Combine RUN commands
[ ] Use .dockerignore
[ ] Run as non-root
[ ] Add a health check
[ ] Use ARG for build time
[ ] Copy specific files
[ ] EXPOSE ports correctly

Conclusion

Following best practices results in Dockerfiles that are faster, more secure, and more efficient. For applications, apply these practices in all Dockerfiles.