Docker & Docker Compose

1. The Problem Docker Solves

You've definitely heard the phrase "it works on my machine". That's the entire reason Docker exists.

Here's the scenario: you build a Node.js app on your laptop. It uses Node 20, PostgreSQL 15, Redis, and a specific version of some npm package. Everything works perfectly. Then you send it to your teammate, and it crashes. Why? Because they have Node 18, a different PostgreSQL version, and their Redis isn't even running.

Docker packages your application along with everything it needs to run -- the OS libraries, the runtime, the dependencies, the config files -- into a single portable unit called a container. This container runs the same way on your laptop, your teammate's laptop, a staging server, or AWS.

2. Containers vs Virtual Machines

Before Docker, we used Virtual Machines (VMs) to solve the "it works on my machine" problem. Both solve the same problem but in very different ways.

Virtual Machines

A VM is like renting an entire apartment. You get your own walls, your own plumbing, your own electricity -- a full copy of an operating system running on top of your host OS. This is heavy. Each VM might use 1-2 GB of RAM just to exist, and it takes minutes to start.

Containers

A container is like renting a room in a shared house. You have your own private space (your app, your files, your dependencies), but you share the walls, plumbing, and electricity (the host OS kernel) with other rooms. This is lightweight. Containers use megabytes of RAM and start in seconds.

3. Core Concepts

There are three things you need to understand: images, containers, and registries.

Images

An image is a blueprint -- a read-only template that contains your application code, runtime, libraries, and everything it needs. Think of it like a class in programming: it defines what something looks like, but it's not running yet.

Images are built in layers. Each instruction in your Dockerfile creates a new layer. Docker caches these layers, so if you change line 8 of your Dockerfile, only layers 8+ get rebuilt -- everything before is cached. This makes builds fast.

Containers

A container is a running instance of an image. If the image is the class, the container is the object. You can run multiple containers from the same image, just like you can create multiple objects from one class.

Each container gets its own isolated filesystem, networking, and process space. It thinks it's the only thing running on the machine.

Registries

A registry is like GitHub but for Docker images. The biggest public registry is Docker Hub. When you type docker pull node:20, Docker downloads the Node.js 20 image from Docker Hub. You can also push your own images there, or use private registries like AWS ECR or GitHub Container Registry.

4. Writing a Dockerfile

A Dockerfile is a text file with instructions that tell Docker how to build your image. Each line is a command. Let's break down a real one:

Basic Node.js Dockerfile

# Start from the official Node.js 20 image (based on Debian Linux)
FROM node:20-slim

# Set the working directory inside the container
WORKDIR /app

# Copy package files first (for better caching)
COPY package.json package-lock.json ./

# Install dependencies
RUN npm ci

# Copy the rest of your source code
COPY . .

# Tell Docker this app listens on port 3000
EXPOSE 3000

# The command to run when the container starts
CMD ["node", "server.js"]

Python Dockerfile

FROM python:3.12-slim

WORKDIR /app

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

COPY . .

EXPOSE 8000

CMD ["python", "app.py"]

Common Dockerfile Instructions

.dockerignore

Just like .gitignore, a .dockerignore file tells Docker what NOT to copy. Always create one:

node_modules
.git
.env
*.log
dist
.DS_Store

Without this, COPY . . would copy your entire node_modules folder into the image (even though you're running npm install inside the container). That wastes time and bloats your image.

5. Essential Docker Commands

Building and Running

# Build an image from a Dockerfile in the current directory
# -t names/tags the image so you can reference it later
docker build -t myapp .

# Run a container from the image
# -p maps host port 3000 to container port 3000
docker run -p 3000:3000 myapp

# Run in detached mode (background) with a name
docker run -d --name my-server -p 3000:3000 myapp

# Run with environment variables
docker run -e DATABASE_URL=postgres://... -p 3000:3000 myapp

# Run interactively (useful for debugging)
docker run -it myapp bash

Managing Containers

# List running containers
docker ps

# List ALL containers (including stopped)
docker ps -a

# Stop a running container
docker stop my-server

# Start a stopped container
docker start my-server

# Remove a stopped container
docker rm my-server

# Stop and remove in one step
docker rm -f my-server

# View container logs
docker logs my-server

# Follow logs in real-time (like tail -f)
docker logs -f my-server

# Execute a command in a running container
docker exec -it my-server bash

Managing Images

# List all images
docker images

# Pull an image from Docker Hub
docker pull postgres:16

# Remove an image
docker rmi myapp

# Remove all unused images, containers, networks
docker system prune

# See how much disk space Docker is using
docker system df

6. Volumes & Networking

The Problem: Containers Are Ephemeral

When a container is deleted, everything inside it is gone. If you're running a PostgreSQL container and you docker rm it, all your database data disappears. That's where volumes come in.

Volumes

A volume is a folder on your host machine that's mounted into the container. Data written to the volume persists even after the container is deleted.

# Named volume (Docker manages the location)
docker run -d --name db \
  -v pgdata:/var/lib/postgresql/data \
  -p 5432:5432 \
  postgres:16

# Bind mount (you choose the location)
# Maps your local ./src folder to /app/src in the container
docker run -d --name dev \
  -v $(pwd)/src:/app/src \
  -p 3000:3000 \
  myapp

Networking

Containers are isolated by default -- they can't talk to each other or the outside world unless you set up networking.

# Create a network
docker network create mynet

# Run containers on the same network
docker run -d --name db --network mynet postgres:16
docker run -d --name api --network mynet -p 3000:3000 myapp

# Now "api" can connect to "db" using the container name as hostname
# Connection string: postgres://user:pass@db:5432/mydb

7. Docker Compose -- Multi-Container Apps

Running individual docker run commands with all those flags gets tedious fast, especially when you have multiple containers that need to talk to each other. That's what Docker Compose solves.

Docker Compose lets you define your entire application stack in a single YAML file (docker-compose.yml), then start everything with one command.

Basic docker-compose.yml

# docker-compose.yml
services:
  # Your Node.js API
  api:
    build: .                    # Build from Dockerfile in current directory
    ports:
      - "3000:3000"             # Map port 3000
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/mydb
      - REDIS_URL=redis://cache:6379
    depends_on:
      - db
      - cache
    volumes:
      - ./src:/app/src          # Bind mount for hot reload in dev

  # PostgreSQL Database
  db:
    image: postgres:16          # Use official image from Docker Hub
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=mydb
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data   # Persist data

  # Redis Cache
  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"

# Define named volumes
volumes:
  pgdata:

Service Configuration Options

services:
  myservice:
    image: node:20              # Use a pre-built image
    # OR
    build:                      # Build from Dockerfile
      context: ./backend        # Directory containing Dockerfile
      dockerfile: Dockerfile.dev  # Custom Dockerfile name

    ports:
      - "3000:3000"             # HOST:CONTAINER

    environment:                # Inline env vars
      - NODE_ENV=development
    env_file:                   # Or load from file
      - .env

    volumes:
      - ./code:/app             # Bind mount
      - nodemodules:/app/node_modules  # Named volume

    restart: unless-stopped     # Restart policy

    command: npm run dev        # Override the CMD from Dockerfile

    depends_on:
      db:
        condition: service_healthy  # Wait for health check

    healthcheck:                # Define health check
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

8. Docker Compose Commands

# Start all services (build if needed)
docker compose up

# Start in detached mode (background)
docker compose up -d

# Rebuild images before starting
docker compose up --build

# Stop all services
docker compose down

# Stop and remove volumes (deletes database data!)
docker compose down -v

# View logs for all services
docker compose logs

# Follow logs for a specific service
docker compose logs -f api

# Run a one-off command in a service
docker compose exec api bash

# List running services
docker compose ps

# Restart a specific service
docker compose restart api

# Scale a service (run multiple instances)
docker compose up -d --scale api=3

9. Real-World Example: Full Stack App

Here's a complete setup for a typical full-stack app with a React frontend, Node.js API, PostgreSQL database, and Redis cache.

Project Structure

my-app/
  frontend/
    Dockerfile
    package.json
    src/
  backend/
    Dockerfile
    package.json
    src/
  docker-compose.yml
  .env

Backend Dockerfile

# backend/Dockerfile
FROM node:20-slim

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .

EXPOSE 4000
CMD ["node", "src/server.js"]

Frontend Dockerfile

# frontend/Dockerfile
FROM node:20-slim

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .

EXPOSE 5173
CMD ["npm", "run", "dev", "--", "--host"]

docker-compose.yml

services:
  frontend:
    build: ./frontend
    ports:
      - "5173:5173"
    volumes:
      - ./frontend/src:/app/src
    depends_on:
      - api

  api:
    build: ./backend
    ports:
      - "4000:4000"
    environment:
      - DATABASE_URL=postgres://dev:devpass@db:5432/myapp
      - REDIS_URL=redis://cache:6379
    volumes:
      - ./backend/src:/app/src
    depends_on:
      - db
      - cache

  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=dev
      - POSTGRES_PASSWORD=devpass
      - POSTGRES_DB=myapp
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  pgdata:

10. Best Practices & Common Mistakes

Do This

• Use -slim or -alpine base images -- node:20-slim is ~200MB vs node:20 at ~1GB. Smaller images build faster and have fewer security vulnerabilities.
• Copy dependency files before source code -- This lets Docker cache the expensive npm install step. Only re-install when package.json changes.
• Always create a .dockerignore -- At minimum, exclude node_modules, .git, and .env.
• Use named volumes for database data -- Never lose your dev data when you restart containers.
• Use depends_on with health checks -- Ensures services actually start in the right order and are ready.
• Pin image versions -- Use postgres:16, not postgres:latest. latest changes without warning and can break your setup.

Don't Do This

• Don't run as root -- Add USER node (or a non-root user) in your Dockerfile for production.
• Don't store secrets in your Dockerfile or docker-compose.yml -- Use .env files (and add them to .gitignore) or Docker secrets.
• Don't use docker compose down -v casually -- The -v flag deletes your volumes. That means your database data is gone.
• Don't install dev tools in production images -- Use multi-stage builds to keep production images lean.

Multi-Stage Build (Production Optimization)

# Stage 1: Build
FROM node:20-slim AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: Production (only the built output)
FROM node:20-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]