Kemal Production API

A production-ready Kemal web API deployed on AWS ECS Fargate with comprehensive CI/CD automation.

🚀 Quick Start

Prerequisites

• AWS CLI configured with appropriate permissions
• Docker installed
• Crystal installed (for local development)
• Git

1. Clone and Setup

git clone <your-repo>
cd kemal
make dev-setup

2. Deploy Infrastructure

# Deploy staging environment
make setup-aws ENVIRONMENT=staging

# Deploy production environment
make setup-aws ENVIRONMENT=production

3. Deploy Application

# Deploy to staging
make deploy-staging

# Deploy to production
make deploy-production

4. Verify Deployment

# Check status
make status

# Health check
make health

# View logs
make logs

📋 Complete Onboarding Strategy

Option 1: GitHub Actions (Recommended)

Best for: Teams, automated deployments, CI/CD pipelines

Setup:

1. Configure GitHub Secrets:

   • Go to your GitHub repository → Settings → Secrets and variables → Actions
   • Add the following secrets:
     • AWS_ACCESS_KEY_ID: Your AWS access key
     • AWS_SECRET_ACCESS_KEY: Your AWS secret key

2. Push to trigger deployment:

   • develop branch → Deploys to staging
   • main branch → Deploys to production

3. Manual deployment:

   • Go to Actions → "Deploy to ECS Fargate" → Run workflow

Benefits:

• ✅ Automated testing and building
• ✅ Multi-environment deployments
• ✅ Pull request validation
• ✅ Built-in security
• ✅ No additional infrastructure needed

Option 2: Manual Deployment Script

Best for: Quick deployments, debugging, one-off updates

Usage:

# Deploy to staging
./scripts/deploy.sh staging

# Deploy to production with custom version
./scripts/deploy.sh production v1.2.3

Benefits:

• ✅ Full control over deployment process
• ✅ Easy debugging and troubleshooting
• ✅ No external dependencies
• ✅ Can be integrated into any CI/CD system

Option 3: Makefile Commands

Best for: Development workflow, quick operations

Usage:

# Build and test
make test
make build

# Deploy
make deploy-staging
make deploy-production

# Monitor
make status
make logs
make health

Benefits:

• ✅ Simple, memorable commands
• ✅ Consistent workflow
• ✅ Built-in validation and checks

🏗️ Infrastructure Overview

AWS Services Used

• ECS Fargate: Container orchestration (serverless)
• ECR: Container registry
• ALB: Load balancer with health checks
• VPC: Network isolation with public/private subnets
• CloudWatch: Logging and monitoring
• Auto Scaling: Automatic scaling based on CPU usage

Architecture

Internet → ALB → ECS Fargate (Private Subnets) → Kemal API
                ↓
            CloudWatch Logs

Security Features

• ✅ Containers run in private subnets
• ✅ Non-root user execution
• ✅ Security groups restrict access
• ✅ IAM roles with least privilege
• ✅ SSL/TLS support (with custom domain)

🔄 Deployment Process

Automated Pipeline (GitHub Actions)

1. Test: Run Crystal specs and Ameba linting
2. Build: Create Docker image with optimizations
3. Push: Upload to ECR with proper tagging
4. Deploy: Update ECS service with new image
5. Verify: Wait for service stability and health checks

Manual Process

1. Build Docker image locally
2. Push to ECR
3. Update ECS task definition
4. Update ECS service
5. Wait for deployment completion

📊 Monitoring and Observability

Built-in Monitoring

• Health Checks: /health endpoint monitored by ALB
• Logs: All logs sent to CloudWatch
• Metrics: CPU, memory, request count, error rates
• Auto-scaling: Scales based on CPU utilization (70% threshold)

Manual Monitoring

# Check service status
make status

# View real-time logs
make logs

# Health check
make health

# Get service URL
make url

🔐 Security Best Practices

Implemented

• ✅ Container runs as non-root user
• ✅ Private subnets for containers
• ✅ Security groups with minimal access
• ✅ IAM roles with least privilege
• ✅ Secrets stored in GitHub Secrets

Recommended Additions

• 🔄 Regular security scans
• 🔄 SSL certificate for custom domain
• 🔄 VPC endpoints for AWS services
• 🔄 CloudTrail for audit logs

🎯 Environment Strategy

Staging Environment

• Purpose: Testing, validation, pre-production
• Resources: 256 CPU, 512MB RAM
• Scaling: 1-2 instances
• Deployment: develop branch or manual

Production Environment

• Purpose: Live application serving users
• Resources: 512 CPU, 1024MB RAM
• Scaling: 2-4 instances
• Deployment: main branch or manual
• Features: Enhanced monitoring, custom domain

🚨 Rollback Strategy

Automatic Rollback

• ECS deployment circuit breaker enabled
• Automatic rollback on health check failures
• CloudWatch alarms for monitoring

Manual Rollback

# Rollback to previous version
aws ecs update-service \
  --cluster kemal-api-staging \
  --service kemal-api-staging-service \
  --task-definition kemal-api-staging-task:PREVIOUS_REVISION

📈 Scaling Strategy

Auto-scaling Configuration

• CPU-based scaling: 70% CPU utilization threshold
• Scale-out cooldown: 300 seconds
• Scale-in cooldown: 300 seconds
• Min instances: 1 (staging), 2 (production)
• Max instances: 4

Manual Scaling

# Scale to specific count
aws ecs update-service \
  --cluster kemal-api-staging \
  --service kemal-api-staging-service \
  --desired-count 3

🔧 Development Workflow

Local Development

# Setup development environment
make dev-setup

# Run tests
make test

# Build locally
make build

# Run locally
cd app && crystal run src/main.cr

Deployment Workflow

# 1. Make changes and test locally
make test

# 2. Commit and push to develop (staging deployment)
git push origin develop

# 3. After testing, merge to main (production deployment)
git push origin main

# 4. Monitor deployment
make status
make health

📞 Troubleshooting

Common Issues

Deployment fails:

# Check ECS service events
aws ecs describe-services \
  --cluster kemal-api-staging \
  --services kemal-api-staging-service

# Check container logs
make logs

Service unhealthy:

# Check health endpoint
make health

# Check ALB target health
aws elbv2 describe-target-health \
  --target-group-arn $TARGET_GROUP_ARN

High latency:

# Check resource usage
make status

# Check auto-scaling
aws application-autoscaling describe-scalable-targets \
  --service-namespace ecs \
  --resource-ids service/kemal-api-staging-cluster/kemal-api-staging-service

Useful Commands

# Get service URL
make url

# Check infrastructure status
aws cloudformation describe-stacks \
  --stack-name kemal-api-staging

# View recent deployments
aws ecs describe-services \
  --cluster kemal-api-staging \
  --services kemal-api-staging-service \
  --query 'services[0].deployments'

🎉 Next Steps

1. Custom Domain: Add your domain and SSL certificate
2. Enhanced Monitoring: Set up CloudWatch dashboards and alarms
3. Database Integration: Add RDS or DynamoDB for data persistence
4. CDN: Add CloudFront for static content delivery
5. CI/CD Enhancement: Add security scanning and automated testing

📚 Additional Resources

• Deployment Guide - Detailed deployment strategies
• AWS ECS Documentation
• Kemal Framework
• Crystal Language

---

Ready to deploy? Start with make dev-setup and follow the quick start guide above!