localstack-article-demo

Demo infrastructure for bootstrapping local authentication and API routing with LocalStack Pro.

This project starts a LocalStack container and runs two init scripts that:

• create an Amazon Cognito User Pool, app client, and admin group
• create an API Gateway v2 HTTP API
• attach a JWT authorizer backed by Cognito
• add proxy routes for sample API prefixes

Project Structure

infra/
  docker-compose.yml
  localstack/
    init/
      01-setup-auth.sh
      02-gateway.sh

What Gets Created

Cognito (01-setup-auth.sh)

• User Pool: myapp-development
• App Client: myapp-web (no client secret)
• Group: admin
• Temporary file used by next step: /tmp/myapp-cognito.env

The script is idempotent. If the user pool already exists, it reuses existing resources.

API Gateway (02-gateway.sh)

• HTTP API name: myapp-local
• CORS for local frontend origins (http://localhost:3000, http://localhost:5173)
• JWT authorizer using values from /tmp/myapp-cognito.env
• Routes (exact + proxy) for:
  • /api/route1
  • /api/route2
  • /api/route3
  • /api/route4
• Default stage: $default

By default, routes proxy to my-service:8001. You can override this with MYSERVICE_HOST.

Prerequisites

• Docker with Compose support
• LocalStack Pro auth token (LOCALSTACK_AUTH_TOKEN)

Quick Start

From the repository root:

export LOCALSTACK_AUTH_TOKEN="<your-token>"
docker compose -f infra/docker-compose.yml up -d

Check health:

curl -sf http://localhost:4566/_localstack/health

View logs:

docker logs -f myapp-localstack

Stop services:

docker compose -f infra/docker-compose.yml down

Remove persisted LocalStack data:

docker compose -f infra/docker-compose.yml down -v

Useful Endpoints

• LocalStack edge endpoint: http://localhost:4566
• API invoke base (printed in startup logs):
  • http://localhost:4566/_aws/execute-api/<API_ID>/$default

Common Checks

List HTTP APIs:

docker exec myapp-localstack awslocal apigatewayv2 get-apis

List Cognito user pools:

docker exec myapp-localstack awslocal cognito-idp list-user-pools --max-results 10