A cloud engineering and DevOps portfolio project that takes a small FastAPI application through a production-style deployment lifecycle: local development, Docker containerization, Amazon ECR image storage, Amazon ECS Fargate deployment, Terraform infrastructure management, GitHub Actions CI/CD, and CloudWatch monitoring with SNS alerts.
The application is a small, production-minded task management API built with FastAPI and SQLite. It is intentionally simple so the main focus stays on infrastructure, automation, deployment, networking, monitoring, and operational readiness.
This project was built to practice real-world cloud engineering workflows using a small, focused application. The project demonstrates how a containerized application can move from local development to a managed AWS container platform using repeatable infrastructure and deployment practices.
The main goals of this project were to:
- Build and run a small FastAPI application locally
- Containerize the application with Docker
- Push Docker images to Amazon ECR
- Deploy the containerized app to Amazon ECS Fargate
- Manage infrastructure with Terraform
- Configure Terraform remote state with S3
- Automate testing and deployment with GitHub Actions
- Add CloudWatch logging, alarms, and SNS notifications
- Document operational troubleshooting with a runbook
| Layer | Technology |
|---|---|
| Language | Python 3.12 |
| Framework | FastAPI |
| Server | Uvicorn |
| Database | SQLite via aiosqlite |
| Config | pydantic-settings |
| Tests | pytest + httpx |
| Linting | Ruff |
- Docker
- Amazon ECR
- Amazon ECS Fargate
- AWS IAM
- Amazon CloudWatch
- Amazon SNS
- Amazon S3
- Terraform
- GitHub Actions
The application is a small task manager API with basic health and task endpoints.
| Method | Path | Description | Request Body | Response |
|---|---|---|---|---|
| GET | /healthz |
Liveness check | — | {"status": "ok"} |
| GET | /readyz |
Readiness check (DB ping) | — | {"status": "ok"} |
| GET | /api/tasks/ |
List all tasks | — | Task[] |
| POST | /api/tasks/ |
Create a task | {"title": "..."} |
Task (201) |
| PATCH | /api/tasks/{id} |
Update a task | {"title"?: "...", "completed"?: bool} |
Task |
| DELETE | /api/tasks/{id} |
Delete a task | — | 204 No Content |
Task schema:
{
"id": "uuid",
"title": "string",
"completed": false,
"created_at": "2025-01-01T00:00:00+00:00"
}Interactive docs: http://localhost:8000/docs
| Variable | Default | Description |
|---|---|---|
APP_ENV |
development |
Environment name (development / production) |
DATABASE_URL |
./data/tasks.db |
Path to SQLite database file |
LOG_LEVEL |
INFO |
Python logging level |
PORT |
8000 |
Port the server listens on |
The application is packaged into a Docker image and pushed to Amazon ECR. ECS Fargate runs the container as a managed serverless container workload. Terraform manages the AWS infrastructure baseline, while GitHub Actions handles CI/CD for testing, image builds, and ECS deployments.
Developer
|
v
GitHub Repository
|
v
GitHub Actions
|
|-- Run lint and tests
|-- Build Docker image
|-- Push image to Amazon ECR
|-- Deploy new task definition to ECS
v
Amazon ECR
|
v
Amazon ECS Fargate
|
|-- CloudWatch Logs
|-- CloudWatch Metrics
v
CloudWatch Alarms
|
v
SNS Email Notifications
The project uses the following AWS resources:
| Resource | Purpose |
|---|---|
| Amazon ECR | Stores Docker images |
| Amazon ECS Cluster | Groups ECS services and tasks |
| ECS Fargate Service | Keeps the application task running |
| ECS Task Definition | Defines container image, CPU, memory, port, logs, and runtime platform |
| IAM Task Execution Role | Allows ECS to pull images from ECR and send logs to CloudWatch |
| Security Group | Controls inbound and outbound traffic for the ECS task |
| CloudWatch Log Group | Stores application logs from ECS tasks |
| CloudWatch Alarms | Monitors CPU and memory utilization |
| SNS Topic | Sends alert notifications by email |
| S3 Bucket | Stores Terraform remote state |
Terraform is used to manage the AWS infrastructure baseline.
Terraform currently manages:
- ECR repository
- ECS cluster
- ECS task definition
- ECS Fargate service
- ECS task execution role
- Security group and rules
- CloudWatch log group
- CloudWatch alarms
- SNS topic and email subscription
- S3 remote backend configuration for Terraform state
Terraform state is stored remotely in S3 to make the infrastructure workflow safer and more realistic.
GitHub Actions is used for CI/CD.
The CI workflow validates the application by:
- Installing dependencies
- Running lint checks
- Running tests
- Building the Docker image to verify the container build
The ECS deployment workflow:
- Authenticates to AWS using GitHub OIDC
- Logs in to Amazon ECR
- Builds a Linux x86_64 Docker image
- Tags the image with the Git commit SHA
- Pushes the image to ECR
- Renders a new ECS task definition
- Deploys the new task definition to the ECS service
- Waits for the service to stabilize
Terraform manages the infrastructure baseline. GitHub Actions manages application delivery.
Terraform answers:
What cloud resources should exist?
GitHub Actions answers:
How do we test, package, publish, and deploy a new app version?
The ECS service is created and managed by Terraform, but GitHub Actions can deploy new task definition revisions with updated Docker image tags. Terraform uses ignore_changes for the ECS service task definition to avoid fighting with CI/CD over the currently deployed app version.
Because this project was developed on an Apple Silicon Mac, Docker can build ARM64 images by default. ECS was configured to run the task as Linux x86_64.
To avoid architecture mismatch errors, the Docker image is built as:
linux/amd64
And the ECS task definition uses:
Operating system: LINUX
CPU architecture: X86_64
This fixes the common ECS error:
/usr/local/bin/uvicorn: exec format error
Requirements: Python 3.12+
python -m venv .venv
source .venv/bin/activateCopy the env file and optionally edit it, then install packages:
cp .env.example .env
pip install -r requirements.txtmake runOr:
uvicorn app.main:app --reload --reload-dir appThe API is available at http://localhost:8000.
make testTests use an isolated in-memory SQLite database per test — no shared state.
make lintmake docker-buildOr:
docker build -t production-ready:local .make docker-runOr:
docker run --rm -p 8000:8000 production-ready:localThe SQLite database is persisted in a named Docker volume (db_data) so data survives container restarts.
Stop:
docker compose downWhen building locally on Apple Silicon, build for Linux x86_64:
docker buildx build \
--platform linux/amd64 \
-t production-ready:manual-v2-amd64 .Navigate to the Terraform environment:
cd infra/terraform/environments/devInitialize Terraform:
terraform initFormat files:
terraform fmt -recursiveValidate configuration:
terraform validatePreview changes:
terraform planApply changes:
terraform applyCloudWatch and SNS are used for monitoring and alerting.
Monitoring includes:
- ECS task logs in CloudWatch Logs
- CPU utilization alarm
- Memory utilization alarm
- SNS email notifications
- Operational runbook for incident response
The SNS email subscription must be confirmed before alerts are delivered. If the confirmation email is missing, check the spam folder.
The project includes a runbook for operational troubleshooting:
docs/runbook.md
The runbook covers:
- App is unreachable
- ECS task keeps stopping
- Deployment failure
- High CPU alarm
- High memory alarm
- Docker architecture mismatch
- ECR push failures
- Terraform drift
- SNS notification issues
- Rollback steps
- Cost-control steps
production-ready/
├── app/
│ ├── main.py # App entry point: lifespan, middleware, routes, health
│ ├── config.py # Environment-based configuration
│ ├── api/
│ │ └── tasks.py # Task route handlers
│ ├── models/
│ │ └── task.py # Pydantic request/response models
│ ├── services/
│ │ └── task_service.py # Business logic and SQL queries
│ ├── db/
│ │ └── database.py # DB init, connection dependency
│ └── middleware/
│ └── logging.py # Request logging middleware
├── tests/
│ ├── conftest.py # Test fixtures
│ ├── test_health.py # Health endpoint tests
│ └── test_tasks.py # Task CRUD and validation tests
├── infra/
│ ├── docker/ # Compose overrides and related assets
│ ├── kubernetes/ # Kubernetes manifests (future EKS path)
│ └── terraform/ # Terraform modules and environments
├── .github/workflows/ # CI and ECS deploy workflows
├── docs/ # Architecture notes, runbooks, and guides
├── Dockerfile
├── docker-compose.yml
├── Makefile
├── requirements.txt
└── .env.example
- Direct SQL over ORM: The schema is one table. Raw parameterized SQL is clearer and avoids SQLAlchemy session lifecycle complexity.
- aiosqlite: Keeps the entire stack async-native. SQLite handles concurrent reads well; writes are serialized at the file level.
- Non-root Docker user: The container runs as
appuserrather than root — a basic but important production security practice. - Layer-optimized Dockerfile: Dependencies are installed before source is copied, so editing app code does not bust the pip cache layer.
- SQLite write concurrency: SQLite supports one writer at a time. This is fine for a single-container deployment. If horizontal scaling is needed in a later phase, PostgreSQL would be the upgrade path.
Additional project documentation is available in the docs/ folder.
| Document | Purpose |
|---|---|
docs/architecture.md |
Explains the system architecture |
docs/ecr-notes.md |
Notes on ECR image storage and Docker pushes |
docs/ecs-networking-notes.md |
Explains ECS networking, VPCs, subnets, route tables, and security groups |
docs/terraform-notes.md |
Explains Terraform setup, modules, imports, remote state, and ECS resources |
docs/github-actions.md |
Explains the CI/CD pipeline and strategy for deployment |
docs/monitoring-notes.md |
Explains CloudWatch, SNS, alarms, and monitoring setup |
docs/runbook.md |
Operational troubleshooting guide |
docs/cleanup.md |
Cleanup and cost-control instructions |
This project helped reinforce several cloud and DevOps concepts:
- How Docker images move from local development to a cloud registry
- How ECS task definitions and services work together
- How VPC networking affects public access to ECS tasks
- Why security groups control inbound and outbound traffic
- Why IAM task execution roles are required for ECR pulls and CloudWatch logs
- How Terraform imports existing AWS resources into state
- Why Terraform remote state matters
- How CI/CD and Terraform should have clear ownership boundaries
- Why image architecture matters when deploying from Apple Silicon to ECS
- How monitoring and runbooks support operational readiness
Potential improvements include:
- Place ECS tasks in private subnets behind an Application Load Balancer
- Add HTTPS with AWS Certificate Manager
- Add a custom domain using Route 53
- Add ECS service autoscaling
- Add EventBridge alerts for stopped ECS tasks
- Add a CloudWatch dashboard
- Add stricter least-privilege IAM policies
- Manage GitHub OIDC IAM resources with Terraform
- Add Kubernetes manifests and migrate workload to EKS
- Add application-level metrics
- Add blue/green or canary deployment strategy
To avoid unnecessary AWS costs, clean up resources when not actively using the project.
Common cleanup steps:
terraform destroyYou may also need to manually review:
- ECS running services/tasks
- ECR images
- CloudWatch log groups
- SNS subscriptions
- S3 Terraform state bucket
Do not delete the Terraform remote state bucket unless you are intentionally retiring the project and no longer need the state.
This project demonstrates an end-to-end DevOps workflow for a containerized application on AWS. It includes application development, Docker containerization, ECR image publishing, ECS Fargate deployment, Terraform infrastructure management, GitHub Actions CI/CD, CloudWatch monitoring, SNS alerting, and incident response documentation.