Skip to content

Update README and architecture docs #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rusets merged 1 commit into from
Dec 10, 2025
Merged

Update README and architecture docs #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 25 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Docker-ecs-deployment
# Docker ECS Deployment — Scale-to-Zero Fargate Demo

<p align="center">
<img src="https://img.shields.io/badge/Terraform-IaC-5C4EE5?logo=terraform" />
Expand Down Expand Up @@ -66,6 +66,15 @@ flowchart LR
```
---

## **OpenAPI-First Wake API**

- The wake HTTP API is defined via an **OpenAPI 3** spec in `infra/api/openapi-wake.yaml`.
- Terraform uses this spec to configure **API Gateway HTTP API** (routes, methods, integration).
- Security and structure of the spec are covered by the same **Checkov** policies as the Terraform code.
- This keeps the API definition **versioned**, **reviewable in PRs**, and easy to reuse in other clients.

---

## **Prerequisites**

- AWS account (**us-east-1** recommended)
Expand Down Expand Up @@ -103,17 +112,17 @@ terraform apply -auto-approve tfplan

## **Key AWS Services Used**

| Service | Purpose |
|------------------|-----------------------------------------------------------------|
| **API Gateway** | Entry point for wake requests → triggers the Wake Lambda |
| **AWS Lambda** | Wake and Auto-Sleep logic (scale ECS to 1 → back to 0) |
| **Amazon ECS** | Fargate service running the Node.js application |
| **AWS Fargate** | Serverless compute for containers (no EC2, scale-to-zero ready) |
| **Amazon ECR** | Storage for Docker container images |
| **Amazon VPC** | Public-only networking, subnets, Internet Gateway |
| **CloudWatch** | Logs for Lambda, API Gateway, ECS |
| **EventBridge** | Scheduler that triggers Auto-Sleep every minute |
| **S3 + DynamoDB**| Terraform backend (state + locking) |
| Service | Purpose |
|------------------|----------------------------------------------------------------|
| **API Gateway** | Wake HTTP endpoint (OpenAPI spec) → calls Wake Lambda |
| **AWS Lambda** | Wake and Auto-Sleep logic (scale ECS to 1 → back to 0) |
| **Amazon ECS** | Fargate service running the Node.js application |
| **AWS Fargate** | Serverless compute for containers (no EC2, scale-to-zero ready)|
| **Amazon ECR** | Storage for Docker container images |
| **Amazon VPC** | Public-only networking, subnets, Internet Gateway |
| **CloudWatch** | Logs for Lambda, API Gateway, ECS |
| **EventBridge** | Scheduler that triggers Auto-Sleep every minute |
| **S3 + DynamoDB**| Terraform backend (state + locking) |

---

Expand Down Expand Up @@ -182,6 +191,7 @@ docker-ecs-deployment
├── autosleep/ # Auto-sleep Lambda (Python)
├── build/ # Built Lambda ZIPs (Terraform-generated)
├── infra/ # All Terraform infrastructure
│ └── api/openapi-wake.yaml # OpenAPI spec for the wake HTTP API
├── docs/ # Architecture, ADRs, runbooks
├── .github/ # CI/CD workflows + templates
├── README.md
Expand Down Expand Up @@ -482,8 +492,8 @@ Each version runs the full set of format, validation, lint, and security checks.
- **Static analysis**
- `tflint --recursive`
- **Security scanning**
- `tfsec` (via `aquasecurity/tfsec-action`)
- `checkov` (via `.checkov.yml` policy file)
- `tfsec` (via `aquasecurity/tfsec-action`) for Terraform resources
- `checkov` (via `.checkov.yml` policy file) for Terraform + OpenAPI spec

If any of these steps fail for any Terraform version, the CI check on the pull request is marked as failed.

Expand All @@ -494,8 +504,8 @@ If any of these steps fail for any Terraform version, the CI check on the pull r
- `.github/workflows/terraform-ci.yml` – CI workflow definition
- `.tflint.hcl` – TFLint configuration
- `.checkov.yml` – Checkov policy and skipped rules for this demo design
- `infra/api/openapi-wake.yaml` – OpenAPI spec for the wake HTTP API
- `infra/` – Terraform root module and all infrastructure code

---

## **Screenshots**
Expand Down
2 changes: 2 additions & 0 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ docker-ecs-deployment/
│ ├── image_build.tf # Terraform-driven Docker build & push to ECR
│ ├── wake.tf # Wake/Autosleep Lambdas + EventBridge + IAM
│ ├── logs.tf # CloudWatch Log Groups for app and Lambdas
│ ├── api/ # OpenAPI specs for API Gateway routes
│ │ └── openapi-wake.yaml # Spec for wake endpoint (HTTP API)
│ ├── api-mapping.tf # API Gateway + custom domain / mappings
│ ├── main.tf # High-level module wiring / orchestration
│ └── outputs.tf # Exported values (URLs, ARNs, IDs)
Expand Down