Skip to content

ECS Deployment Guide

This document describes the ECS deployment configuration for the Sundial API.

Overview

The Sundial API is deployed to AWS ECS using Pulumi infrastructure as code. The deployment includes:

  • ECS Fargate service
  • Application Load Balancer with health checks
  • ECR container registry
  • VPC with public subnets

Health Checks

The ECS deployment includes a health check endpoint at /health that returns:

{
  "status": "ok",
  "timestamp": "2025-06-15T04:10:39.000Z"
}

Health Check Configuration

  • Path: /health
  • Port: 8080
  • Protocol: HTTP
  • Healthy threshold: 2 consecutive successes
  • Unhealthy threshold: 3 consecutive failures
  • Interval: 30 seconds
  • Timeout: 5 seconds
  • Grace period: 300 seconds

Deployment Commands

Local Development with Docker Compose and Localstack

  1. Build and start all services (localstack + API): bash npm run deploy:localstack

  2. Check service status: bash docker compose -f docker-compose.localstack.yml ps

  3. Test the deployment: bash npm run test:health npm run test:e2e:localstack

  4. View logs: bash docker compose -f docker-compose.localstack.yml logs sundial-api docker compose -f docker-compose.localstack.yml logs localstack

  5. Stop all services: bash npm run localstack:down

Docker Compose Configuration

The docker-compose.localstack.yml includes:

  • Localstack: Simulates AWS services (ECS, ECR, EC2, ELBv2, etc.)
  • Sundial API: Built from local Dockerfile and connected to localstack
  • Health Checks: Both services have health checks configured
  • Networking: Shared network for service communication
  • Environment Variables: Configured for localstack endpoints

Production Deployment

  1. Build and push Docker image: bash docker build -t sundial-api . docker tag sundial-api:latest <ECR_REPOSITORY_URL>:latest docker push <ECR_REPOSITORY_URL>:latest

  2. Deploy infrastructure using Pulumi: bash pulumi up --stack production

Troubleshooting

Local Docker Compose Issues

  1. Check service health: bash docker compose -f docker-compose.localstack.yml ps

  2. View service logs: bash docker compose -f docker-compose.localstack.yml logs sundial-api docker compose -f docker-compose.localstack.yml logs localstack

  3. Test localstack connectivity: bash curl http://localhost:4566/health

  4. Test API health endpoint: bash curl http://localhost:8080/health

Health Check Failures

If health checks are failing:

  1. Check that the application is listening on port 8080
  2. Verify the /health endpoint is accessible
  3. Check ECS service logs for startup errors
  4. Ensure security groups allow traffic on port 8080
  5. Verify Docker networking allows service communication
  6. Wait for localstack health check to pass before testing API

High AWS Config Charges

The previous ECS deployment was disabled due to high AWS Config charges from failing health checks. This has been resolved by:

  1. Adding a proper health check endpoint
  2. Configuring appropriate health check timeouts and thresholds
  3. Setting a health check grace period of 300 seconds
  4. Using Docker Compose for reliable local testing before production deployment