Docker for Backend Developers: Containerize Your API (2026)

# Naive Dockerfile — works but has problems
FROM node:20

WORKDIR /app
COPY . .
RUN npm install
EXPOSE 3000
CMD ["node", "src/index.js"]

# Multi-stage build for a TypeScript Node.js API
# Stage 1: Install all dependencies and build TypeScript
FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files first — Docker caches this layer
# Only re-runs npm install when package.json or lock file changes
COPY package*.json ./
RUN npm ci --include=dev

# Copy source and build
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

# Stage 2: Production image — only runtime dependencies
FROM node:20-alpine AS production

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

WORKDIR /app

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

# Copy compiled JavaScript from builder stage
COPY --from=builder /app/dist ./dist

# Set ownership
RUN chown -R nodeapp:nodejs /app
USER nodeapp

# Health check — Docker will mark container unhealthy if this fails
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1

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

# .dockerignore
node_modules
dist
.git
.gitignore
.env
.env.*
*.md
coverage
.nyc_output
docker-compose*.yml
Dockerfile*
.eslintrc*
.prettierrc*
tsconfig.json
jest.config.*

// src/routes/health.ts
import { Router } from 'express';
import { pool } from '../db';

const router = Router();

router.get('/health', async (req, res) => {
  try {
    // Check database connectivity
    await pool.query('SELECT 1');
    res.json({
      status: 'ok',
      timestamp: new Date().toISOString(),
      uptime: process.uptime(),
    });
  } catch (err) {
    res.status(503).json({
      status: 'error',
      message: 'Database unavailable',
    });
  }
});

export default router;

# docker-compose.yml
version: '3.8'

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      DATABASE_URL: postgresql://apiuser:devpassword@postgres:5432/apidb
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}      # Loaded from .env file
    depends_on:
      postgres:
        condition: service_healthy   # Wait for DB to be ready
      redis:
        condition: service_started
    restart: unless-stopped
    networks:
      - api-network

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: apiuser
      POSTGRES_PASSWORD: devpassword
      POSTGRES_DB: apidb
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U apiuser -d apidb"]
      interval: 10s
      timeout: 5s
      retries: 5
    ports:
      - "5432:5432"   # Only expose in development
    networks:
      - api-network

  redis:
    image: redis:7-alpine
    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
    volumes:
      - redis-data:/data
    networks:
      - api-network

  # Development-only: run migrations before starting
  migrate:
    build:
      context: .
      target: builder
    command: npx prisma migrate deploy
    environment:
      DATABASE_URL: postgresql://apiuser:devpassword@postgres:5432/apidb
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - api-network
    profiles: ["migrate"]  # Only runs when explicitly invoked

networks:
  api-network:
    driver: bridge

volumes:
  postgres-data:
  redis-data:

# Start everything
docker compose up -d

# Run migrations
docker compose --profile migrate run migrate

# View logs from all services
docker compose logs -f

# View logs from a specific service
docker compose logs -f api

# Stop everything (preserves volumes/data)
docker compose down

# Stop and delete volumes (start completely fresh)
docker compose down -v

JWT_SECRET=dev-jwt-secret-change-in-production
POSTGRES_PASSWORD=devpassword

# docker-compose.dev.yml — extends docker-compose.yml
version: '3.8'

services:
  api:
    build:
      target: builder   # Use builder stage for hot reloading
    command: npx ts-node-dev --respawn src/index.ts
    volumes:
      - ./src:/app/src  # Mount source for live reloading
    environment:
      NODE_ENV: development
      LOG_LEVEL: debug
    ports:
      - "9229:9229"     # Node.js debugger port

# Development with hot reloading
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# GitHub Actions example — .github/workflows/deploy.yml
- name: Run database migrations
  run: |
    docker run --rm \
      --network host \
      -e DATABASE_URL=${{ secrets.DATABASE_URL }} \
      ${{ env.IMAGE }}:${{ env.SHA }} \
      npx prisma migrate deploy

- name: Deploy new container
  run: docker compose up -d api  # Only deploys after migrations succeed

# Build and tag an image
docker build -t my-api:latest .

# Run a container from an image (without compose)
docker run -d \
  --name my-api \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://..." \
  my-api:latest

# Get a shell inside a running container
docker exec -it my-api sh

# Check resource usage
docker stats

# View all images and their sizes
docker images

# Remove unused images (free disk space)
docker image prune -a

# Remove stopped containers
docker container prune

# Copy a file from a container (useful for extracting logs)
docker cp my-api:/app/logs/error.log ./error.log

# Port 5432 is exposed in docker-compose.yml for dev
# Connect with:
# Host: localhost
# Port: 5432
# Database: apidb
# User: apiuser
# Password: devpassword

# Or use psql directly inside the container
docker exec -it <postgres-container-name> psql -U apiuser -d apidb