4. Phase 2: production deployment

Phase 2 takes the working API from your laptop to production. Containerise with Docker, deploy with ECS Fargate, monitor with CloudWatch, automate with GitHub Actions.

The pieces in this phase are the Ch27-29 primitives (Compose for local dev, multi-stage Dockerfile, ECR, ECS Fargate, RDS, ElastiCache, ALB, CloudWatch, GitHub Actions) wired into the capstone's own repo and service names. Where a topic was covered in detail in an earlier chapter, the section here points at the previous chapter rather than rewalking it; what the page does walk is the wiring specific to this project.

Docker Compose local environment

docker compose up brings up FastAPI, PostgreSQL, and Redis in three containers on a private network with persistent volumes for the database and cache. The PostgreSQL version, the Redis configuration, and the environment variable shape all match what the production stack uses; bugs that depend on the runtime surface (timezone, locale, file permissions inside the container) show up here rather than waiting for AWS to surface them.

version: '3.8'

services:
  # PostgreSQL Database
  postgres:
    image: postgres:15-alpine
    container_name: news-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: news_platform
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - news-network

  # Redis Cache
  redis:
    image: redis:7-alpine
    container_name: news-redis
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
    networks:
      - news-network

  # FastAPI Application
  api:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: news-api
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/news_platform
      - REDIS_URL=redis://redis:6379
      - NEWSAPI_KEY=${NEWSAPI_KEY}
      - GUARDIAN_API_KEY=${GUARDIAN_API_KEY}
      - REDDIT_CLIENT_ID=${REDDIT_CLIENT_ID}
      - REDDIT_CLIENT_SECRET=${REDDIT_CLIENT_SECRET}
      - REDDIT_REDIRECT_URI=${REDDIT_REDIRECT_URI}
    ports:
      - "8000:8000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - news-network
    volumes:
      - ./app:/app/app  # Mount for hot reload during development
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

volumes:
  postgres_data:
  redis_data:

networks:
  news-network:
    driver: bridge

Starting Your Local Environment.

# Start all services
docker compose up

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

# View logs for specific service:
docker compose logs -f api

# Run database migrations:
docker compose exec api alembic upgrade head

# Stop everything:
docker compose down

# Stop and remove volumes (fresh start):
docker compose down -v

Testing locally with Docker Compose

The whole stack runs in Compose before any of it runs on AWS. Configuration issues, container-to-container networking problems, and integration bugs surface here, where the feedback loop is seconds rather than minutes-to-rebuild-an-ECS-task. The Compose stack is the diagnostic environment; AWS is the deployment target.

• Bring up the stack, run migrations. Start the three services and apply the schema:

# 1. Start all services (detached mode)
docker compose up -d

# 2. Verify all containers are healthy
docker compose ps
# Expected output: api (healthy), postgres (healthy), redis (healthy)

# 3. Run database migrations
docker compose exec api alembic upgrade head

# 4. Check application logs
docker compose logs api --follow

# 5. Test the health endpoint
curl http://localhost:8000/health
# Expected: {"status": "healthy", "database": "connected", "redis": "connected"}

# 6. Test article fetching
curl "http://localhost:8000/api/articles?query=python&source=newsapi"
# Should return JSON with articles from NewsAPI

• Local testing checklist. Six probes, run in order; each one isolates a different layer:
• Database connectivity: Run docker compose exec postgres psql -U postgres -d news_platform -c "\dt" to verify tables exist
• Redis caching: Make the same API request twice. Second request should be faster (<10ms vs ~800ms). Check logs for cache hits.
• External API integration: Test each source individually: /api/articles?source=newsapi, source=guardian, source=reddit
• OAuth flow: Visit http://localhost:8000/auth/reddit/login and complete Reddit authorization. Verify tokens are stored.
• Error handling: Test with invalid API keys (temporarily change .env values). API should return proper error messages, not crash.
• Concurrent requests: Use ab (Apache Bench) to send 100 concurrent requests: ab -n 100 -c 10 http://localhost:8000/health
• Debugging when a probe fails. Diagnose from the closest layer outwards: container logs first, then exec into the container to check connectivity, then check network reachability between containers.

# Check container logs for errors
docker compose logs api | grep -i error
docker compose logs postgres | tail -20
docker compose logs redis | tail -20

# Execute commands inside containers
docker compose exec api python -c "from app.database import engine; print(engine)"
docker compose exec postgres psql -U postgres -d news_platform -c "SELECT COUNT(*) FROM articles;"
docker compose exec redis redis-cli PING

# Test network connectivity between containers
docker compose exec api ping postgres
docker compose exec api curl redis:6379

# Restart individual services
docker compose restart api
docker compose restart postgres

# Rebuild API container (if code changes aren't reflected)
docker compose up -d --build api

The local stack has to be green before the AWS deployment starts. A broken build deployed to ECS still costs real time to diagnose, and the diagnostic path on AWS is strictly slower than the one on the laptop.

Optimising for production: multi-stage builds

A multi-stage Dockerfile separates the build environment (which has the C toolchain, the dev headers, and the build-time Python packages) from the runtime environment (which only has the runtime interpreter and the compiled wheels). The final image is built off the runtime stage and contains nothing the running container doesn't need.

For a Python app of this shape the difference is typically several hundred megabytes; the chapter's own image goes from around 500MB single-stage to roughly 200MB multi-stage. The cost is split across two places that matter: pull time on every new ECS task and the attack surface inside the container.

# ==========================================
# Stage 1: Builder - Install dependencies
# ==========================================
FROM python:3.11-slim as builder

WORKDIR /app

# Install system dependencies for Python packages
RUN apt-get update && apt-get install -y \
    gcc \
    postgresql-client \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements and install
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt

# ==========================================
# Stage 2: Runtime - Minimal final image
# ==========================================
FROM python:3.11-slim

WORKDIR /app

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

# Copy Python packages from builder
COPY --from=builder /root/.local /root/.local

# Copy application code
COPY ./app /app/app
COPY ./alembic /app/alembic
COPY ./alembic.ini /app/alembic.ini

# Make sure scripts in .local are usable
ENV PATH=/root/.local/bin:$PATH

# Create non-root user
RUN useradd -m -u 1000 appuser && \
    chown -R appuser:appuser /app
USER appuser

# Expose port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=2)"

# Start application
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Building and testing the image.

# Build the image
docker build -t news-api:latest .

# Check image size (should be ~200-300MB)
docker images news-api:latest

# Test the image locally
docker run -p 8000:8000 \
  -e DATABASE_URL=postgresql://postgres:postgres@localhost:5432/news_platform \
  -e REDIS_URL=redis://localhost:6379 \
  --env-file .env \
  news-api:latest

AWS deployment walkthrough

Five things have to land in order: push the image to ECR; register the task definition; provision RDS and ElastiCache; stand up the ALB and target group; create the ECS service. Chapter 28 walks each one in detail; this section gives the concrete commands and JSON for the capstone's repo and service names.

Push the image to Amazon ECR.

# Authenticate Docker with ECR
aws ecr get-login-password --region us-east-1 | \
    docker login --username AWS --password-stdin \
    <your-account-id>.dkr.ecr.us-east-1.amazonaws.com

# Create repository if it doesn't exist
aws ecr create-repository --repository-name news-platform-api --region us-east-1

# Get repository URI
ECR_URI=$(aws ecr describe-repositories \
    --repository-names news-platform-api \
    --query 'repositories[0].repositoryUri' \
    --output text)

# Tag and push
docker tag news-api:latest $ECR_URI:latest
docker push $ECR_URI:latest

• ECS task definition. One JSON document describes the container: CPU and memory reservations, environment variables, secrets pulled from Secrets Manager, the CloudWatch log group, and the health check. Updating it registers a new revision; updating the service to point at the new revision is what actually deploys.

{
  "family": "news-platform-task",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "executionRoleArn": "arn:aws:iam::<account-id>:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "name": "news-api",
      "image": "<account-id>.dkr.ecr.us-east-1.amazonaws.com/news-platform-api:latest",
      "portMappings": [
        {
          "containerPort": 8000,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {
          "name": "DATABASE_URL",
          "value": "postgresql://newsadmin:password@<rds-endpoint>:5432/news_platform"
        },
        {
          "name": "REDIS_URL",
          "value": "redis://<elasticache-endpoint>:6379"
        }
      ],
      "secrets": [
        {
          "name": "NEWSAPI_KEY",
          "valueFrom": "arn:aws:secretsmanager:us-east-1:<account-id>:secret:newsapi-key"
        },
        {
          "name": "GUARDIAN_API_KEY",
          "valueFrom": "arn:aws:secretsmanager:us-east-1:<account-id>:secret:guardian-key"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/news-platform",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "api"
        }
      }
    }
  ]
}

CI/CD pipeline with GitHub Actions

Every push to main runs pytest with coverage, builds and tags the Docker image with the commit SHA, pushes to ECR, registers a new task-definition revision, updates the service, and waits for stability. The whole sequence is gated on tests passing; a failing pytest stops the workflow before anything reaches AWS.

name: Deploy to AWS ECS

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

env:
  AWS_REGION: us-east-1
  ECR_REPOSITORY: news-platform-api
  ECS_SERVICE: news-platform-service
  ECS_CLUSTER: news-platform-cluster
  ECS_TASK_DEFINITION: news-platform-task
  CONTAINER_NAME: news-api

jobs:
  test:
    name: Run Tests
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: news_platform_test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

      redis:
        image: redis:7-alpine
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 6379:6379

    steps:
      - uses: actions/checkout@v3

      - name: Set up Python 3.11
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest pytest-cov pytest-asyncio

      - name: Run tests
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/news_platform_test
          REDIS_URL: redis://localhost:6379
        run: |
          pytest --cov=app --cov-report=term-missing --cov-fail-under=70

  deploy:
    name: Deploy to AWS
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'

    steps:
      - uses: actions/checkout@v3

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Login to Amazon ECR
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v1

      - name: Build, tag, and push image
        id: build-image
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
          docker tag $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG $ECR_REGISTRY/$ECR_REPOSITORY:latest
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:latest
          echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT

      - name: Update ECS task definition
        id: task-def
        uses: aws-actions/amazon-ecs-render-task-definition@v1
        with:
          task-definition: task-definition.json
          container-name: ${{ env.CONTAINER_NAME }}
          image: ${{ steps.build-image.outputs.image }}

      - name: Deploy to ECS
        uses: aws-actions/amazon-ecs-deploy-task-definition@v1
        with:
          task-definition: ${{ steps.task-def.outputs.task-definition }}
          service: ${{ env.ECS_SERVICE }}
          cluster: ${{ env.ECS_CLUSTER }}
          wait-for-service-stability: true

CloudWatch monitoring dashboard

The dashboard tracks the four golden signals (latency at P50 and P99, request rate, 4xx and 5xx counts, CPU and memory saturation) pulled from two sources: the ALB for request-level metrics and the ECS service for container-level metrics. Four widgets, one per signal. Anything beyond that is a second-pass investigation tool, not a dashboard widget.

{
  "widgets": [
    {
      "type": "metric",
      "properties": {
        "metrics": [
          ["AWS/ApplicationELB", "TargetResponseTime", {"stat": "Average"}],
          ["...", {"stat": "p99"}]
        ],
        "period": 60,
        "stat": "Average",
        "region": "us-east-1",
        "title": "Latency (Response Time)",
        "yAxis": {
          "left": {
            "min": 0,
            "label": "Seconds"
          }
        }
      }
    },
    {
      "type": "metric",
      "properties": {
        "metrics": [
          ["AWS/ApplicationELB", "RequestCount", {"stat": "Sum"}]
        ],
        "period": 60,
        "stat": "Sum",
        "region": "us-east-1",
        "title": "Traffic (Requests Per Minute)"
      }
    },
    {
      "type": "metric",
      "properties": {
        "metrics": [
          ["AWS/ApplicationELB", "HTTPCode_Target_5XX_Count", {"stat": "Sum"}],
          ["AWS/ApplicationELB", "HTTPCode_Target_4XX_Count", {"stat": "Sum"}]
        ],
        "period": 60,
        "stat": "Sum",
        "region": "us-east-1",
        "title": "Errors (By Status Code)"
      }
    },
    {
      "type": "metric",
      "properties": {
        "metrics": [
          ["AWS/ECS", "CPUUtilization", {"stat": "Average", "dimensions": {"ServiceName": "news-platform-service", "ClusterName": "news-platform-cluster"}}],
          ["AWS/ECS", "MemoryUtilization", {"stat": "Average", "dimensions": {"ServiceName": "news-platform-service", "ClusterName": "news-platform-cluster"}}]
        ],
        "period": 60,
        "stat": "Average",
        "region": "us-east-1",
        "title": "Saturation (Resource Utilization)"
      }
    }
  ]
}

Creating the dashboard.

# Create dashboard from config file
aws cloudwatch put-dashboard \
    --dashboard-name NewsPlatformProduction \
    --dashboard-body file://dashboard-config.json

# View dashboard URL
echo "https://console.aws.amazon.com/cloudwatch/home?region=us-east-1#dashboards:name=NewsPlatformProduction"

At the end of Phase 2 the platform is on AWS: ECS Fargate containers behind an ALB, RDS PostgreSQL with automated backups, ElastiCache Redis, GitHub Actions deploying on every merge to main, and a CloudWatch dashboard tracking the four golden signals. The remaining piece is the troubleshooting reference for when the deployment doesn't go smoothly the first time.

Troubleshooting common deployment issues

First-time AWS deployments hit a small set of recurring failures. The six below cover the bulk of what surfaces; each has a symptom, a diagnostic step, and the fixes that resolve it. The pattern across all of them is "the application code is fine; the wiring isn't" -- security groups, IAM permissions, VPC routing.

• Issue 1: ECS tasks keep restarting. Symptoms: ECS service shows tasks starting and immediately stopping. Health checks never pass. CloudWatch logs show startup errors or database connection failures.

Diagnosis:

# 1. Check CloudWatch logs for startup errors
aws logs tail /ecs/news-api --follow

# 2. Verify DATABASE_URL is correctly formatted
# Should be: postgresql://username:password@rds-endpoint:5432/dbname

# 3. Test database connectivity from task
# Use ECS Exec to shell into running task
aws ecs execute-command --cluster news-cluster \
  --task TASK_ID --container api \
  --command "/bin/sh" --interactive

# Inside container, test database:
python -c "import psycopg2; psycopg2.connect('postgresql://...')"

Common fixes:

• Verify RDS security group allows inbound traffic on port 5432 from ECS tasks
• Confirm DATABASE_URL environment variable is set correctly in task definition
• Check RDS instance is in "available" state, not "backing-up" or "modifying"
• Ensure task execution role has permissions to pull secrets from Secrets Manager
• Run database migrations: alembic upgrade head may not have completed
• Issue 2: ALB health checks failing. Symptoms: the load balancer shows all targets as "unhealthy." Tasks are running but not receiving traffic. /health returns errors or times out.

Common fixes:

• Verify health check path is /health (not /) in target group settings
• Check ECS task security group allows inbound HTTP (port 8000) from ALB security group
• Confirm tasks have public IP addresses OR routes to ALB (check subnet configuration)
• Test health endpoint directly: curl http://TASK_PUBLIC_IP:8000/health
• Review health check thresholds: 2 consecutive failures with 30s interval is too aggressive. Try 3 failures, 10s interval.
• Check application logs for errors during health check handling
• Issue 3: external APIs timing out. Symptoms: requests to NewsAPI, the Guardian, or Reddit time out. Works locally but fails in ECS. CloudWatch logs show httpx.TimeoutException or ConnectionError.

Common fixes:

• Verify ECS task security group allows outbound HTTPS traffic (port 443) to 0.0.0.0/0
• If using private subnets, confirm NAT Gateway is configured and routes 0.0.0.0/0 -> NAT Gateway
• Test external connectivity from inside container: curl https://newsapi.org
• Check VPC route tables: private subnets need route to NAT Gateway, public subnets to Internet Gateway
• Increase httpx timeout from 30s to 60s for external API calls
• Issue 4: Redis connection refused. Symptoms: cache operations fail. Logs show redis.exceptions.ConnectionError: Error 111 connecting to redis:6379. Connection refused.

Common fixes:

• Verify ElastiCache endpoint is correct in REDIS_URL environment variable
• Check ElastiCache security group allows inbound traffic on port 6379 from ECS tasks
• Confirm ElastiCache cluster is in same VPC as ECS tasks
• ElastiCache doesn't have public endpoints, tasks must be in same VPC
• Test connectivity: telnet REDIS_ENDPOINT 6379 from inside ECS task
• Issue 5: Secrets Manager access denied. Symptoms: tasks fail to start with Error retrieving secret: User is not authorized to perform: secretsmanager:GetSecretValue.

Common fixes:

• Verify task execution role (not task role) has secretsmanager:GetSecretValue permission
• Check secret ARN in task definition matches actual secret ARN
• Confirm secret exists in same region as ECS cluster
• Review IAM policy attached to task execution role for typos in resource ARN
• Issue 6: CI/CD pipeline deployment timeouts. Symptoms: the GitHub Actions workflow times out waiting for the ECS service to stabilise. The deployment takes more than 15 minutes or never completes.

Common fixes:

• Check ECS deployment circuit breaker settings, may be rolling back due to health check failures
• Review ECS service events: aws ecs describe-services --cluster news-cluster --services news-api
• Verify new task definition is valid: incorrect environment variables cause infinite restart loops
• Increase GitHub Actions timeout from 10 minutes to 20 minutes for initial deployments
• Check if ECS cluster has capacity: insufficient CPU/memory prevents new tasks from starting
• General debugging order. When something isn't working, run this sequence in order; the cheap checks are first so the expensive ones only run when needed:

1. CloudWatch logs first. The application's stdout and stderr land in the configured log group; most failures show up there before they show up anywhere else.
2. Security groups second. Most AWS connectivity failures are a security group not allowing the inbound port from the source the connection is actually coming from.
3. Isolate the layer. Test database, Redis, external API, and the ALB health-check endpoint independently before treating it as one combined failure.
4. Compare against the working Compose stack. The local environment is the reference; if it works there and not on AWS, the difference is in the runtime configuration, not the code.
5. Visualise the networking in the console. The route-table and security-group views in the AWS Console make misconfigured network paths obvious in a way the CLI doesn't.
6. Check the AWS Service Health Dashboard. Rare, but worth ruling out before spending an hour on something that turns out to be regional.

The list grows over time; every failure mode you debug yourself becomes another entry. The runbook is part of the deliverable, not separate from it.

Next, in section 5, we add one extension feature on top of the deployed system: sentiment analysis is the walked example, with full-text search, webhooks, GraphQL, and async fan-out as the alternatives.