Containerization & Deployment

Introduction

Containers provide the isolation and portability that microservices need. Each service packages its dependencies, runs in its own environment, and can be deployed independently. From deploying microservices in production, I've learned that proper containerization is foundational to success.

This article covers Docker best practices, multi-stage builds, and Docker Compose for local development.

Why Containers for Microservices?

Benefit	Description
Isolation	Each service runs in its own environment
Portability	Works the same in dev, test, and prod
Resource efficiency	Share OS kernel, lighter than VMs
Fast startup	Seconds vs minutes for VMs
Immutability	Build once, run anywhere

Dockerfile Best Practices

Multi-Stage Build

# Dockerfile for Python FastAPI service

# Stage 1: Build dependencies
FROM python:3.11-slim AS builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt

# Stage 2: Runtime image
FROM python:3.11-slim AS runtime

# Create non-root user
RUN groupadd -r appgroup && useradd -r -g appgroup appuser

WORKDIR /app

# Install runtime dependencies only
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Copy wheels from builder
COPY --from=builder /wheels /wheels
RUN pip install --no-cache-dir /wheels/* && rm -rf /wheels

# Copy application code
COPY --chown=appuser:appgroup ./src ./src
COPY --chown=appuser:appgroup ./alembic ./alembic
COPY --chown=appuser:appgroup alembic.ini .

# Switch to non-root user
USER appuser

# Expose port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health/live || exit 1

# Run application
CMD ["python", "-m", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

Layer Caching Optimization

# Bad: Copy everything first (breaks cache on any change)
# COPY . .
# RUN pip install -r requirements.txt

# Good: Copy requirements first (cache pip install)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Then copy source code
COPY ./src ./src

Environment-Specific Builds

# Dockerfile with build arguments

ARG PYTHON_VERSION=3.11
FROM python:${PYTHON_VERSION}-slim AS base

# Common setup
WORKDIR /app
COPY requirements.txt .

# Development target
FROM base AS development
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install --no-cache-dir pytest pytest-cov debugpy
COPY . .
CMD ["python", "-m", "debugpy", "--listen", "0.0.0.0:5678", "-m", "uvicorn", "src.main:app", "--reload", "--host", "0.0.0.0"]

# Production target
FROM base AS production
RUN pip install --no-cache-dir -r requirements.txt
COPY ./src ./src
USER nobody
CMD ["python", "-m", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--workers", "4"]

# Build for development
docker build --target development -t order-service:dev .

# Build for production
docker build --target production -t order-service:prod .

Docker Compose for Local Development

Complete Microservices Stack

# docker-compose.yml
version: "3.8"

services:
  # API Gateway
  gateway:
    build:
      context: ./gateway
      target: development
    ports:
      - "8000:8000"
    environment:
      - ORDER_SERVICE_URL=http://order-service:8001
      - USER_SERVICE_URL=http://user-service:8002
      - PRODUCT_SERVICE_URL=http://product-service:8003
      - JWT_SECRET=${JWT_SECRET:-dev-secret}
    depends_on:
      - order-service
      - user-service
      - product-service
    volumes:
      - ./gateway/src:/app/src:ro
    networks:
      - microservices

  # Order Service
  order-service:
    build:
      context: ./order-service
      target: development
    ports:
      - "8001:8000"
    environment:
      - DATABASE_URL=postgresql+asyncpg://postgres:postgres@order-db:5432/orders
      - REDIS_URL=redis://redis:6379/0
      - RABBITMQ_URL=amqp://guest:guest@rabbitmq:5672/
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
    depends_on:
      order-db:
        condition: service_healthy
      redis:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
    volumes:
      - ./order-service/src:/app/src:ro
    networks:
      - microservices

  # User Service
  user-service:
    build:
      context: ./user-service
      target: development
    ports:
      - "8002:8000"
    environment:
      - DATABASE_URL=postgresql+asyncpg://postgres:postgres@user-db:5432/users
      - REDIS_URL=redis://redis:6379/1
    depends_on:
      user-db:
        condition: service_healthy
      redis:
        condition: service_healthy
    volumes:
      - ./user-service/src:/app/src:ro
    networks:
      - microservices

  # Product Service
  product-service:
    build:
      context: ./product-service
      target: development
    ports:
      - "8003:8000"
    environment:
      - DATABASE_URL=postgresql+asyncpg://postgres:postgres@product-db:5432/products
      - ELASTICSEARCH_URL=http://elasticsearch:9200
    depends_on:
      product-db:
        condition: service_healthy
      elasticsearch:
        condition: service_healthy
    volumes:
      - ./product-service/src:/app/src:ro
    networks:
      - microservices

  # Order Database
  order-db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=orders
    volumes:
      - order-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - microservices

  # User Database
  user-db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=users
    volumes:
      - user-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - microservices

  # Product Database
  product-db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=products
    volumes:
      - product-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - microservices

  # Redis
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - microservices

  # RabbitMQ
  rabbitmq:
    image: rabbitmq:3-management-alpine
    ports:
      - "5672:5672"
      - "15672:15672"  # Management UI
    environment:
      - RABBITMQ_DEFAULT_USER=guest
      - RABBITMQ_DEFAULT_PASS=guest
    volumes:
      - rabbitmq-data:/var/lib/rabbitmq
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "check_running"]
      interval: 10s
      timeout: 10s
      retries: 5
    networks:
      - microservices

  # Elasticsearch
  elasticsearch:
    image: elasticsearch:8.11.0
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    ports:
      - "9200:9200"
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data
    healthcheck:
      test: ["CMD-SHELL", "curl -s http://localhost:9200/_cluster/health | grep -q 'green\\|yellow'"]
      interval: 10s
      timeout: 10s
      retries: 10
    networks:
      - microservices

  # Jaeger for tracing
  jaeger:
    image: jaegertracing/all-in-one:1.52
    ports:
      - "16686:16686"  # UI
      - "4317:4317"    # OTLP gRPC
      - "4318:4318"    # OTLP HTTP
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    networks:
      - microservices

  # Prometheus for metrics
  prometheus:
    image: prom/prometheus:v2.48.0
    ports:
      - "9090:9090"
    volumes:
      - ./infrastructure/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
    networks:
      - microservices

  # Grafana for dashboards
  grafana:
    image: grafana/grafana:10.2.2
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana-data:/var/lib/grafana
      - ./infrastructure/grafana/provisioning:/etc/grafana/provisioning:ro
    depends_on:
      - prometheus
    networks:
      - microservices

networks:
  microservices:
    driver: bridge

volumes:
  order-db-data:
  user-db-data:
  product-db-data:
  redis-data:
  rabbitmq-data:
  elasticsearch-data:
  prometheus-data:
  grafana-data:

Development Overrides

# docker-compose.override.yml (auto-loaded in development)
version: "3.8"

services:
  order-service:
    build:
      target: development
    volumes:
      - ./order-service/src:/app/src
      - ./order-service/tests:/app/tests
    environment:
      - DEBUG=true
      - LOG_LEVEL=DEBUG
    command: ["python", "-m", "uvicorn", "src.main:app", "--reload", "--host", "0.0.0.0"]

  user-service:
    build:
      target: development
    volumes:
      - ./user-service/src:/app/src
      - ./user-service/tests:/app/tests
    environment:
      - DEBUG=true
      - LOG_LEVEL=DEBUG
    command: ["python", "-m", "uvicorn", "src.main:app", "--reload", "--host", "0.0.0.0"]

Production Configuration

# docker-compose.prod.yml
version: "3.8"

services:
  order-service:
    build:
      target: production
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 256M
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
    environment:
      - DEBUG=false
      - LOG_LEVEL=INFO
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health/live"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Service Startup Scripts

Entrypoint Script

#!/bin/bash
# docker-entrypoint.sh

set -e

# Wait for dependencies
echo "Waiting for database..."
while ! nc -z ${DB_HOST:-db} ${DB_PORT:-5432}; do
  sleep 1
done
echo "Database is ready!"

# Run migrations
echo "Running database migrations..."
python -m alembic upgrade head

# Execute the main command
exec "$@"

# In Dockerfile
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["python", "-m", "uvicorn", "src.main:app", "--host", "0.0.0.0"]

Health-Aware Startup

# src/main.py
from fastapi import FastAPI
from contextlib import asynccontextmanager
import asyncio


async def wait_for_dependencies():
    """Wait for all dependencies to be ready."""
    max_retries = 30
    
    # Wait for database
    for i in range(max_retries):
        try:
            await database.connect()
            break
        except Exception:
            if i == max_retries - 1:
                raise
            await asyncio.sleep(1)
    
    # Wait for Redis
    for i in range(max_retries):
        try:
            await redis_client.ping()
            break
        except Exception:
            if i == max_retries - 1:
                raise
            await asyncio.sleep(1)
    
    # Wait for RabbitMQ
    for i in range(max_retries):
        try:
            await message_broker.connect()
            break
        except Exception:
            if i == max_retries - 1:
                raise
            await asyncio.sleep(1)


@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup
    await wait_for_dependencies()
    await setup_telemetry()
    await start_background_workers()
    
    yield
    
    # Shutdown
    await stop_background_workers()
    await database.disconnect()
    await redis_client.close()
    await message_broker.close()


app = FastAPI(lifespan=lifespan)

Container Security

Security Scanning

# Add to CI/CD pipeline
# .github/workflows/security.yml

name: Security Scan

on: [push]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build image
        run: docker build -t myapp:${{ github.sha }} .
      
      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: myapp:${{ github.sha }}
          format: 'sarif'
          output: 'trivy-results.sarif'
          severity: 'CRITICAL,HIGH'
      
      - name: Upload scan results
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: 'trivy-results.sarif'

Secure Dockerfile

# Security best practices

# 1. Use specific version tags
FROM python:3.11.7-slim-bookworm

# 2. Don't run as root
RUN groupadd -r app && useradd -r -g app app

# 3. Remove unnecessary packages
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    && rm -rf /var/lib/apt/lists/* \
    && apt-get purge -y --auto-remove

# 4. Use COPY instead of ADD
COPY --chown=app:app requirements.txt .

# 5. Don't store secrets in image
# Use runtime environment variables instead

# 6. Set proper permissions
RUN chmod -R 755 /app

# 7. Use non-root user
USER app

# 8. Set read-only root filesystem (where possible)
# In docker-compose: read_only: true

# 9. Drop capabilities
# In docker-compose:
# cap_drop:
#   - ALL
# cap_add:
#   - NET_BIND_SERVICE

Useful Commands

# Build and start all services
docker compose up --build

# Start specific services
docker compose up order-service user-service

# View logs
docker compose logs -f order-service

# Execute command in running container
docker compose exec order-service python -m pytest

# Run database migrations
docker compose exec order-service alembic upgrade head

# Stop all services
docker compose down

# Stop and remove volumes (clean slate)
docker compose down -v

# Build for production
docker compose -f docker-compose.yml -f docker-compose.prod.yml build

# Scale a service
docker compose up -d --scale order-service=3

Key Takeaways

1. Multi-stage builds - Smaller images, faster deployments

2. Layer caching - Order instructions to maximize cache hits

3. Non-root users - Security best practice

4. Health checks - Enable container orchestration to manage lifecycle

5. Docker Compose for dev - Mirror production locally

What's Next?

With containerized services, we need to manage service-to-service communication at scale. In Article 12: Service Mesh & Governance, we'll explore service mesh concepts, mTLS, and team organization patterns.

---

This article is part of the Microservice Architecture 101 series.