Dockerfile

A Dockerfile is a script containing instructions for building a Docker image automatically.

Dockerfile Structure

# 1. Base Image
FROM ubuntu:22.04

# 2. Metadata
LABEL maintainer="[email protected]"
LABEL version="1.0"

# 3. Environment Variables
ENV APP_HOME=/app
ENV NODE_ENV=production

# 4. Working Directory
WORKDIR $APP_HOME

# 5. Copy Dependencies
COPY package*.json ./

# 6. Install Dependencies
RUN apt-get update && \
    apt-get install -y nodejs npm && \
    rm -rf /var/lib/apt/lists/*

# 7. Copy Source Code
COPY . .

# 8. Build (if needed)
RUN npm run build

# 9. Expose Port
EXPOSE 3000

# 10. Health Check
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:3000/health || exit 1

# 11. Run Command
CMD ["node", "server.js"]

Basic Dockerfile Instructions

FROM

# Base image
FROM ubuntu:22.04

# With a platform
FROM --platform=linux/amd64 node:18-alpine

# Multi-stage build
FROM node:18-alpine AS builder
FROM nginx:alpine

COPY vs ADD

# COPY: Copy regular files
COPY package.json /app/
COPY . /app/

# ADD: Copy with auto-extract
ADD app.tar.gz /app/
ADD https://example.com/file.txt /app/

RUN

# Run a shell command
RUN apt-get update && apt-get install -y nginx

# Run an exec command
RUN ["/usr/bin/node", "server.js"]

CMD vs ENTRYPOINT

# CMD: Can be overridden
CMD ["node", "server.js"]
CMD node server.js

# ENTRYPOINT: Cannot be overridden
ENTRYPOINT ["node"]
CMD ["server.js"]

ENV and ARG

# ENV: Environment variable (present at runtime)
ENV DB_HOST=localhost
ENV DB_PORT=5432

# ARG: Build-time variable
ARG VERSION=1.0
ARG NODE_ENV=production

WORKDIR

# Set the working directory
WORKDIR /app
WORKDIR /app/src

EXPOSE

# Declare the ports that will be used
EXPOSE 80
EXPOSE 443
EXPOSE 3000

HEALTHCHECK

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

Multi-Stage Build

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

# Stage 2: Production
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/server.js"]

Use Case: Application Dockerfile

# Backend API
FROM node:18-alpine

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

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production && \
    npm cache clean --force

# Copy source code
COPY --chown=nodejs:nodejs . .

# Switch to the non-root user
USER nodejs

# Environment
ENV NODE_ENV=production
ENV PORT=3000

EXPOSE 3000

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

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

.dockerignore

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

Best Practices

Use a minimal base image: Alpine Linux for a smaller size
Order instructions correctly: Put COPY package*.json before COPY .
Combine RUN commands: Reduce the number of layers
Use multi-stage builds: For production
Don't run as root: Use a non-root user
Use .dockerignore: Avoid unneeded files
Define a HEALTHCHECK: For monitoring

Everyday Use Case

Case: A developer needs a Dockerfile for the application.

# Build the image
docker build -t myapp-api:1.0 .

# Run the container
docker run -d \
  --name myapp-api \
  -p 3000:3000 \
  -e DB_HOST=database \
  -e DB_NAME=myapp \
  myapp-api:1.0

# Check the logs
docker logs myapp-api

# Enter the container
docker exec -it myapp-api sh

Troubleshooting

Build fails

# Check the build log
docker build -t myapp . 2>&1 | tee build.log

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

"COPY failed" error

# Make sure the file exists
ls -la

# Check .dockerignore
cat .dockerignore

Conclusion

A Dockerfile is the foundation for creating reproducible images. By following best practices, the resulting image will be secure, efficient, and easy to maintain.