{"id":18573135,"url":"https://github.com/localstack-samples/sample-terraform-ecs-apigateway","last_synced_at":"2025-10-13T19:36:49.772Z","repository":{"id":152323923,"uuid":"613918908","full_name":"localstack-samples/sample-terraform-ecs-apigateway","owner":"localstack-samples","description":"Serverless Container-based APIs with Amazon ECS and Amazon API Gateway deployed using LocalStack","archived":false,"fork":false,"pushed_at":"2025-02-23T00:44:13.000Z","size":10087,"stargazers_count":21,"open_issues_count":1,"forks_count":1,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-03-24T18:06:39.537Z","etag":null,"topics":["api-gateway","aws","developer-hub","dynamodb","ecs","ecs-fargate","lambda","localstack","localstack-developer-hub","serverless"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/localstack-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-14T14:29:23.000Z","updated_at":"2025-03-15T18:08:56.000Z","dependencies_parsed_at":"2024-04-08T17:31:43.629Z","dependency_job_id":"01498140-76b6-4a33-b380-e9709740914f","html_url":"https://github.com/localstack-samples/sample-terraform-ecs-apigateway","commit_stats":null,"previous_names":["localstack-samples/sample-terraform-ecs-apigateway"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack-samples%2Fsample-terraform-ecs-apigateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack-samples%2Fsample-terraform-ecs-apigateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack-samples%2Fsample-terraform-ecs-apigateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack-samples%2Fsample-terraform-ecs-apigateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localstack-samples","download_url":"https://codeload.github.com/localstack-samples/sample-terraform-ecs-apigateway/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248176384,"owners_count":21060058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","aws","developer-hub","dynamodb","ecs","ecs-fargate","lambda","localstack","localstack-developer-hub","serverless"],"created_at":"2024-11-06T23:08:07.693Z","updated_at":"2025-10-13T19:36:44.738Z","avatar_url":"https://github.com/localstack-samples.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serverless Container-based APIs with Amazon ECS and Amazon API Gateway\n\n| Key          | Value                                                                                 |\n| ------------ | ------------------------------------------------------------------------------------- |\n| Environment  | \u003cimg src=\"https://img.shields.io/badge/LocalStack-deploys-4D29B4.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAKgAAACoABZrFArwAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAALbSURBVHic7ZpNaxNRFIafczNTGIq0G2M7pXWRlRv3Lusf8AMFEQT3guDWhX9BcC/uFAr1B4igLgSF4EYDtsuQ3M5GYrTaj3Tmui2SpMnM3PlK3m1uzjnPw8xw50MoaNrttl+r1e4CNRv1jTG/+v3+c8dG8TSilHoAPLZVX0RYWlraUbYaJI2IuLZ7KKUWCisgq8wF5D1A3rF+EQyCYPHo6Ghh3BrP8wb1en3f9izDYlVAp9O5EkXRB8dxxl7QBoNBpLW+7fv+a5vzDIvVU0BELhpjJrmaK2NMw+YsIxunUaTZbLrdbveZ1vpmGvWyTOJToNlsuqurq1vAdWPMeSDzwzhJEh0Bp+FTmifzxBZQBXiIKaAq8BBDQJXgYUoBVYOHKQRUER4mFFBVeJhAQJXh4QwBVYeHMQJmAR5GCJgVeBgiYJbg4T8BswYPp+4GW63WwvLy8hZwLcd5TudvBj3+OFBIeA4PD596nvc1iiIrD21qtdr+ysrKR8cY42itCwUP0Gg0+sC27T5qb2/vMunB/0ipTmZxfN//orW+BCwmrGV6vd63BP9P2j9WxGbxbrd7B3g14fLfwFsROUlzBmNM33XdR6Meuxfp5eg54IYxJvXCx8fHL4F3w36blTdDI4/0WREwMnMBeQ+Qd+YC8h4g78wF5D1A3rEqwBiT6q4ubpRSI+ewuhP0PO/NwcHBExHJZZ8PICI/e73ep7z6zzNPwWP1djhuOp3OfRG5kLROFEXv19fXP49bU6TbYQDa7XZDRF6kUUtEtoFb49YUbh/gOM7YbwqnyG4URQ/PWlQ4ASllNwzDzY2NDX3WwioKmBgeqidgKnioloCp4aE6AmLBQzUExIaH8gtIBA/lFrCTFB7KK2AnDMOrSeGhnAJSg4fyCUgVHsolIHV4KI8AK/BQDgHW4KH4AqzCQwEfiIRheKKUAvjuuu7m2tpakPdMmcYYI1rre0EQ1LPo9w82qyNziMdZ3AAAAABJRU5ErkJggg==\"\u003e \u003cimg src=\"https://img.shields.io/badge/AWS-deploys-F29100.svg?logo=amazon\"\u003e                                                                     |\n| Services     | S3, DynamoDB, Elastic Container Service, API Gateway, Cognito, IAM                    |\n| Integrations | Terraform, CloudFormation, AWS CLI                                                    |\n| Categories   | Serverless; Containers; Security, Identity, and Compliance                            |\n| Level        | Intermediate                                                                          |\n| GitHub       | [Repository link](https://github.com/localstack/serverless-api-ecs-apigateway-sample) |\n\n## Introduction\n\nThe Serverless Container-based APIs with Amazon ECS and Amazon API Gateway application sample demonstrate how you can launch and test a sample container-based API. This application sample implements an example API with two services — “Food store” to `PUT` \u0026 `GET` foods, and “Pet store” to `PUT` \u0026 `GET` pets. The application client is implemented using ReactJS, which allows unauthenticated users to use only `GET` requests, while authenticated users can utilize `GET` and `PUT` requests. Users can deploy this application sample on AWS \u0026 LocalStack using CloudFormation \u0026 Terraform with minimal changes. To test this application sample, we will demonstrate how you use LocalStack to deploy the infrastructure on your developer machine and your CI environment.\n\n## Architecture diagram\n\nThe following diagram shows the architecture that this sample application builds and deploys:\n\n![Architecture diagram for Serverless Container-based APIs with Amazon ECS and Amazon API Gateway sample application](./images/serverless-container-api.png)\n\nWe are using the following AWS services and their features to build our infrastructure:\n\n- [Elastic Container Service](https://docs.localstack.cloud/user-guide/aws/elastic-container-service/) to create and deploy our containerized application.\n- [DynamoDB](https://docs.localstack.cloud/user-guide/aws/dynamodb/) as a key-value and document database to persist our data.\n- [API Gateway](https://docs.localstack.cloud/user-guide/aws/apigatewayv2/) to expose the containerized services to the user through HTTP APIs.\n- [Cognito User Pools](https://docs.localstack.cloud/user-guide/aws/cognito/) for user authentication and authorizing requests to container APIs.\n- [Amplify](https://docs.localstack.cloud/user-guide/aws/amplify/) to create the user client with ReactJS to send requests to container APIs.\n- [S3](https://docs.localstack.cloud/user-guide/aws/s3/) to deploy the Amplify application to make the web application available to users.\n- [IAM](https://docs.localstack.cloud/user-guide/aws/iam/) to create policies to specify roles and permissions for various AWS services.\n\n## Prerequisites\n\n- LocalStack Pro with the [`localstack` CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli).\n- [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).\n- [Terraform](https://docs.localstack.cloud/user-guide/integrations/terraform/) with the [`tflocal` wrapper](https://docs.localstack.cloud/user-guide/integrations/terraform/#using-the-tflocal-script).\n- [Node.js](https://nodejs.org/en/download/) with `npm` package manager.\n\nStart LocalStack Pro with the appropriate configuration to enable the S3 website to send requests to the container APIs:\n\n```shell\nexport LOCALSTACK_AUTH_TOKEN=\u003cyour-auth-token\u003e\nEXTRA_CORS_ALLOWED_ORIGINS=http://sample-app.s3.localhost.localstack.cloud:4566 DISABLE_CUSTOM_CORS_APIGATEWAY=1 DEBUG=1 localstack start\n```\n\nThe `DISABLE_CUSTOM_CORS_APIGATEWAY` configuration variable disables CORS override by API Gateway. The `EXTRA_CORS_ALLOWED_ORIGINS` configuration variable allows our website to send requests to the container APIs.\nWe specified DEBUG=1 to get the printed LocalStack logs directly in the terminal (it helps later, when we need to get the Cognito confirmation code).\nIf you prefer running LocalStack in detached mode, you can add the `-d` flag to the `localstack start` command, and use Docker Desktop to view the logs.\n\n## Instructions\n\nYou can build and deploy the sample application on LocalStack by running our `Makefile` commands. Run `make terraform-setup` or `make cloudformation-setup` to create the infrastructure on LocalStack. \nRun `make run` to deploy the S3 Website and get a URL to access the application. Run `make stop` to delete the infrastructure by stopping LocalStack.\n\nAlternatively, here are instructions to deploy it manually step-by-step.\n\n## Creating the infrastructure\n\nTo create the AWS infrastructure locally, you can either use Terraform or CloudFormation.\n\n### Terraform\n\nTo create the infrastructure using Terraform, run the following commands:\n\n```shell\ncd terraform\ntflocal init\ntflocal apply --auto-approve\n```\n\nWe are using the `tflocal` wrapper to configure the local service endpoints, and send the API requests to LocalStack, instead of AWS. You can use the same Terraform configuration to deploy the infrastructure on AWS as well.\n\n\u003e Currently, the Terraform configuration is tested \u0026 validated against `localstack/localstack:3.2.0` image. You can use the `IMAGE_NAME` environment variable to specify the LocalStack image version to ensure that the Terraform configuration works as expected.\n\n#### CloudFormation\n\nTo create the infrastructure using CloudFormation, run the following commands:\n\n```shell\ncd cloudformation\nexport STACK=\"stack1\"\nawslocal cloudformation create-stack --stack-name $STACK --template-body file://ecsapi-demo-cloudformation.yaml\n```\n\nWait for a few seconds for the infrastructure to be created. You can check the status of the stack using the following command:\n\n```shell\nawslocal cloudformation describe-stacks --stack-name $STACK | grep StackStatus\n```\n\nIf the `StackStatus` is `CREATE_COMPLETE`, you can proceed to the next step.\n\n## Building the web application\n\nTo build the web application, navigate to the root directory of the sample application and run the following commands:\n\n```shell\ncd client-application-react\nyarn\nNODE_OPTIONS=--openssl-legacy-provider yarn build\n```\n\nEnsure a `build` directory is created in the `client-application-react` directory.\n\n## Deploying the web application\n\nTo deploy the web application, we will make an S3 bucket and sync the `build` directory to the S3 bucket. Run the following commands from the `client-application-react` directory:\n\n```shell\nawslocal s3 mb s3://sample-app\nawslocal s3 sync build s3://sample-app\n```\n\nTo access the web application, you can run the following commands:\n\n```shell\nexport API_ID=$(awslocal apigatewayv2 get-apis | jq -r '.Items[] | select(.Name==\"ecsapi-demo\") | .ApiId')\nexport POOL_ID=$(awslocal cognito-idp list-user-pools --max-results 1 | jq -r '.UserPools[0].Id')\nexport CLIENT_ID=$(awslocal cognito-idp list-user-pool-clients --user-pool-id $POOL_ID | jq -r '.UserPoolClients[0].ClientId')\nexport URL=\"http://sample-app.s3.localhost.localstack.cloud:4566/index.html?stackregion=us-east-1\u0026stackhttpapi=$API_ID\u0026stackuserpool=$POOL_ID\u0026stackuserpoolclient=$CLIENT_ID\"\necho $URL\n```\n\n## Testing the web application\n\nTo test the web application, follow these steps:\n\n- Open your application URL in your browser if it is displayed in the terminal.\n- Create a user by clicking the **Go to Sign In!** button and navigating to the **Create Account** page.\n- Follow the prompts to fill in your details, and click the **Create account** button.\n- You will be prompted to enter a confirmation code displayed in the terminal, in the LocalStack logs. Use this code to confirm your Account.\n\nOnce you have confirmed your Account, skip the email recovery step, as that endpoint is not yet implemented. The application endpoints can now add and retrieve information on your pets and food. You will find a few entries in the resources folder to get you started and explore the application.\n\n![Serverless Container-based APIs with Amazon ECS and Amazon API Gateway Web Interface](./images/interface.png)\n\n### Visualizing your data\n\nNavigate to [**app.localstack.cloud**](https://app.localstack.cloud/) and go to **Resources** -\u003e **DynamoDB**. You can now see the tables created, as well as the data stored in them:\n\n![Displaying DynamoDB tables in the LocalStack Web Application](./images/web-app-tables.png)\n\n![Displaying DynamoDB table items in the LocalStack Web Application](./images/web-app-items.png)\n\nAlternatively, you can use the AWS CLI to query the table data. For example, to query the `FoodStoreFoods` table, run the following command:\n\n```bash\nawslocal dynamodb scan --table-name FoodStoreFoods\n```\n\n## State Management\n\nThe [Export/Import State feature](https://docs.localstack.cloud/user-guide/state-management/export-import-state/) enables you to export the state of your LocalStack instance into a file and import it into another LocalStack instance. This feature is useful when you want to save your LocalStack instance’s state for later use.\n\nTo save your local AWS infrastructure state, you can use the `export` command with a desired name for your state file as the first argument:\n\n```bash\nlocalstack state export serverless-api-ecs-apigateway-state\n```\n\nThe above command will create a file named `serverless-api-ecs-apigateway-state` to the specified location on the disk.\n\nYou can import the state file we created previously using the `import` command with the file name as the first argument:\n\n```bash\nlocalstack state import serverless-api-ecs-apigateway-state\n```\n\nTo ensure everything is set in place now, follow the previous steps of setting the configuration variables and query the application URL. The state will be restored, and you should be able to see the same data as before.\n\n## GitHub Action\n\nThis application sample hosts an example GitHub Action workflow that starts up LocalStack, deploys the infrastructure, and checks the created resources using `awslocal`. You can find the workflow in the `.github/workflows/main.yml` file. To run the workflow, you can fork this repository and push a commit to the `main` branch.\n\nUsers can adapt this example workflow to run in their own CI environment. LocalStack supports various CI environments, including GitHub Actions, CircleCI, Jenkins, Travis CI, and more. You can find more information about the CI integration in the [LocalStack documentation](https://docs.localstack.cloud/user-guide/ci/).\n\n## Learn more\n\nThe sample application is based on a public [AWS sample app](https://github.com/aws-samples/ecs-apigateway-sample) that deploys ECS containers with API Gateway to connect to. See this AWS blog post for more details:  [Field Notes: Serverless Container-based APIs with Amazon ECS and Amazon API Gateway.](https://aws.amazon.com/blogs/architecture/field-notes-serverless-container-based-apis-with-amazon-ecs-and-amazon-api-gateway/)\n\n## Contributing\n\nWe appreciate your interest in contributing to our project and are always looking for new ways to improve the developer experience. We welcome feedback, bug reports, and even feature ideas from the community.\nPlease refer to the [contributing file](CONTRIBUTING.md) for more details on how to get started. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack-samples%2Fsample-terraform-ecs-apigateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalstack-samples%2Fsample-terraform-ecs-apigateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack-samples%2Fsample-terraform-ecs-apigateway/lists"}