Skip to content

Commit c453140

Browse files
HarshCasperHarshCasper
committed
revamp the readme
1 parent 978161b commit c453140

File tree

1 file changed

+158
-0
lines changed

1 file changed

+158
-0
lines changed

‎README-new.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# ECS Fargate Deployment using CDK
2+
3+
| Key | Value |
4+
| ------------ | --------------------------------------------------------------------------- |
5+
| Environment | LocalStack, AWS |
6+
| Services | ECS, Fargate, ALB, ECR, VPC |
7+
| Integrations | AWS CDK, AWS CLI, Docker, LocalStack |
8+
| Categories | Compute, Networking |
9+
| Level | Intermediate |
10+
| Use Case | ECS Code-Mounting, ECS Debugging |
11+
| GitHub | [Repository link](https://github.com/localstack-samples/sample-cdk-ecs-elb) |
12+
13+
## Introduction
14+
15+
This sample demonstrates how to deploy a containerized application on AWS Fargate using the AWS Cloud Development Kit (CDK). The application infrastructure includes a VPC, ECS cluster, Fargate service, Docker image hosted in ECR, and an Application Load Balancer (ALB) for traffic routing. To test this application sample, we will demonstrate how you use LocalStack to deploy the infrastructure on your developer machine and run the application locally. We will also show how to use ECS code-mounting to apply code changes instantly without rebuilds, and how to debug the application with a Node.js debugger.
16+
17+
## Architecture
18+
19+
The following diagram shows the architecture that this sample application builds and deploys:
20+
21+
![Solution](./docs/img/solution-diags.drawio.png "Solution")
22+
23+
- Virtual Private Cloud (VPC) that sets an isolated network environment to host AWS resources securely.
24+
- [Elastic Container Service (ECS)](https://docs.localstack.cloud/user-guide/aws/ecs/) to manage the deployment and scaling of containerized applications using the Fargate launch type.
25+
- [Elastic Load Balancer (ALB)](https://docs.localstack.cloud/user-guide/aws/elb/) to distribute incoming HTTP/S traffic across ECS tasks.
26+
27+
## Prerequisites
28+
29+
- [`localstack` CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli) with a [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/).
30+
- [AWS CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/) with the [`awslocal` wrapper](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#localstack-aws-cli-awslocal).
31+
- [CDK](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/) with the [`cdklocal`](https://www.npmjs.com/package/aws-cdk-local) wrapper.
32+
- [Node.js](https://nodejs.org/en/download/)
33+
- [`make`](https://www.gnu.org/software/make/) (**optional**, but recommended for running the sample application)
34+
35+
## Installation
36+
37+
To run the sample application, you need to install the required dependencies.
38+
39+
First, clone the repository:
40+
41+
```shell
42+
git clone https://github.com/localstack-samples/sample-cdk-ecs-elb.git
43+
```
44+
45+
Then, navigate to the project directory:
46+
47+
```shell
48+
cd sample-cdk-ecs-elb
49+
```
50+
51+
Next, install the project dependencies by running the following command:
52+
53+
```shell
54+
make install
55+
```
56+
57+
## Deployment
58+
59+
Start LocalStack with the `LOCALSTACK_AUTH_TOKEN` pre-configured:
60+
61+
```shell
62+
localstack auth set-token <your-auth-token>
63+
localstack start
64+
```
65+
66+
To deploy the sample application, run the following command:
67+
68+
```shell
69+
make deploy
70+
```
71+
72+
The output will be similar to the following:
73+
74+
```shell
75+
Outputs:
76+
RepoStack.MyFargateServiceLoadBalancerDNS704F6391 = lb-f6d118e8.elb.localhost.localstack.cloud
77+
RepoStack.MyFargateServiceServiceURL4CF8398A = http://lb-f6d118e8.elb.localhost.localstack.cloud
78+
RepoStack.localstackserviceslb = lb-f6d118e8.elb.localhost.localstack.cloud:4566
79+
RepoStack.serviceslb = lb-f6d118e8.elb.localhost.localstack.cloud
80+
Stack ARN:
81+
arn:aws:cloudformation:us-east-1:000000000000:stack/RepoStack/75719142
82+
83+
✨ Total time: 28.73s
84+
```
85+
86+
## Testing
87+
88+
The output of the deployment will show the URL of the load balancer. You can use this URL to access the application and verify the HTTP response:
89+
90+
```shell
91+
make curl
92+
```
93+
94+
The output will be similar to the following:
95+
96+
```shell
97+
{"message":"Hi LocalStack!"}
98+
```
99+
100+
You can run full end-to-end integration tests using the following command:
101+
102+
```shell
103+
make test
104+
```
105+
106+
## Use Cases
107+
108+
### ECS Code-Mounting
109+
110+
In this sample, ECS code-mounting is implemented using Docker bind mounts to enable real-time sync between your local development environment and the ECS task running in LocalStack.
111+
112+
The CDK configuration defines a volume that maps a local source directory (`src/app`) to a container path (`/app`) inside the ECS task. When deployed via `cdklocal`, LocalStack translates this into a Docker bind mount.
113+
114+
To make use of this:
115+
116+
- Add a volume definition in your ECS task for the local source directory.
117+
- Mount that volume inside your container at the desired path.
118+
- Enable auto-reloading in your application (e.g., `--watch` for Node.js) to reflect code changes instantly.
119+
120+
This approach allows you to test and iterate faster, as demonstrated by editing a file in `src/app` and immediately seeing the updated response when invoking the ECS service.
121+
122+
> [!NOTE]
123+
> LocalStack uses real Docker bind mounts to emulate AWS ECS volume behavior locally, making it ideal for fast feedback loops during development.
124+
125+
### ECS Debugging
126+
127+
This sample also demonstrates how to enable remote debugging for Node.js applications running inside ECS tasks on LocalStack. By exposing a debugging port and connecting via Visual Studio Code, you can inspect, step through, and troubleshoot your running containerized application.
128+
129+
The setup uses the `ECS_DOCKER_FLAGS` environment variable to configure Docker to expose the Node.js debugger on port `9229` and enable debugging with `--inspect-brk`. When LocalStack starts the ECS task, it passes these flags to the Docker container, enabling remote inspection.
130+
131+
To make use of this:
132+
133+
- Set `ECS_DOCKER_FLAGS` to include port mapping and debugging options.
134+
- Restart LocalStack with this configuration.
135+
- Define VSCode tasks and launch configurations to wait for and attach to the remote debugger (samples available in `.vscode` directory).
136+
- Add breakpoints in your code and use the debugger UI to inspect execution.
137+
138+
Once configured, you can `curl` the ELB endpoint to trigger the application and hit breakpoints set in your VSCode editor.
139+
140+
Combined with code-mounting, this setup allows live debugging without needing to rebuild Docker images, making your iteration loop faster.
141+
142+
## Summary
143+
144+
This sample application demonstrates how to provision, deploy, and test a containerized Node.js application on AWS Fargate using AWS CDK and LocalStack. It showcases the following patterns:
145+
146+
- Defining and deploying core AWS resources, such as VPC, ECS, Fargate, and Elastic Load Balancer, using AWS CDK.
147+
- Building and pushing Docker images to Amazon ECR, and integrating them into ECS task definitions.
148+
- Configuring Visual Studio Code for remote debugging of ECS tasks running in LocalStack.
149+
- Using bind mounts with ECS to mount code from the host filesystem into the ECS container for quick hot-reloads.
150+
- Utilizing `cdklocal` and `awslocal` to streamline local deployment and testing workflows.
151+
152+
## Learn More
153+
154+
- [Deep Dive tutorial into ECS hot-reloading & debugging](https://blog.localstack.cloud/developing-debugging-aws-ecs-tasks-localstack-vs-code/)
155+
- [ECS Code-Mounting](https://docs.localstack.cloud/user-guide/aws/ecs/#mounting-local-directories-for-ecs-tasks)
156+
- [Use bind mounts with Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/bind-mounts.html)
157+
- [Remote Debugging for ECS with LocalStack](https://docs.localstack.cloud/user-guide/aws/ecs/#remote-debugging)
158+
- [Deploying AWS CDK applications with LocalStack](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/)

0 commit comments

Comments
 (0)