Skip to content

Commit 0b2aba1

Browse files
mwarmanmwarman
committed
feat: add LocalStack support for local development and testing
- Updated README.md to include LocalStack Guide. - Modified .env.example to add LocalStack configuration options. - Enhanced LambdaStack to accept LocalStack parameters and set environment variables accordingly. - Added aws-cdk-local dependency for LocalStack integration. - Introduced local commands in package.json for managing LocalStack with Docker. - Updated LambdaStack tests to validate LocalStack configuration. - Refactored config utility to handle LocalStack settings. - Created sns-client utility to manage SNS client with LocalStack support. - Added tests for LocalStack configuration in DynamoDB and SNS clients.
1 parent 9d0a95d commit 0b2aba1

23 files changed

Lines changed: 1613 additions & 87 deletions

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,15 @@ node_modules
1212
# dotenv environment variable files
1313
.env*
1414
!.env.example
15+
!.env.local
1516

1617
# build output
1718
build
1819
dist
1920

2021
# AWS CDK
2122
cdk.out
22-
.cdk.staging
23+
.cdk.staging
24+
25+
# LocalStack
26+
localstack-data/

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,10 @@ npm run test:coverage
117117
npm run test:watch
118118
```
119119

120+
### LocalStack Support
121+
122+
This project includes full support for [LocalStack](https://localstack.cloud/), allowing you to run and test the microservice locally without deploying to AWS. See the [LocalStack Guide](docs/LocalStackGuide.md) for details.
123+
120124
## Technology Stack
121125

122126
- **Language:** TypeScript

‎docker-compose.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
services:
2+
localstack:
3+
container_name: lambda-starter-localstack
4+
image: localstack/localstack:4.12
5+
ports:
6+
- '4566:4566'
7+
environment:
8+
# LocalStack configuration
9+
- SERVICES=s3,dynamodb,sns,lambda,apigateway,logs,iam,sts,cloudformation,ssm
10+
- DEBUG=${DEBUG:-0}
11+
- LAMBDA_EXECUTOR=docker
12+
- DOCKER_HOST=unix:///var/run/docker.sock
13+
- AWS_DEFAULT_REGION=us-east-1
14+
# Configure Lambda to access LocalStack from within containers
15+
- LAMBDA_DOCKER_NETWORK=lambda-starter_lambda-starter-network
16+
- LOCALSTACK_HOSTNAME=localstack
17+
# Enable persistence (optional - comment out to disable)
18+
- PERSISTENCE=${PERSISTENCE:-0}
19+
volumes:
20+
# Mount docker socket for Lambda execution
21+
- /var/run/docker.sock:/var/run/docker.sock
22+
# Optional: Persist data between restarts
23+
- ./localstack-data:/var/lib/localstack
24+
networks:
25+
- lambda-starter-network
26+
27+
networks:
28+
lambda-starter-network:
29+
driver: bridge

‎docs/ConfigurationGuide.md‎

Lines changed: 102 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,17 @@ The application configuration is managed through environment variables. These va
1010

1111
The following environment variables are available for configuring the application:
1212

13-
| Variable | Type | Description | Default | Required |
14-
| ---------------------- | ------- | ------------------------------------------------ | ----------- | -------- |
15-
| `TASKS_TABLE` | string | The name of the DynamoDB table for storing tasks | - | Yes |
16-
| `TASK_EVENT_TOPIC_ARN` | string | The ARN of the SNS topic for task events | - | Yes |
17-
| `AWS_REGION` | string | The AWS region where resources are deployed | `us-east-1` | No |
18-
| `LOGGING_ENABLED` | boolean | Enable or disable application logging | `true` | No |
19-
| `LOGGING_LEVEL` | enum | Logging level: `debug`, `info`, `warn`, `error` | `debug` | No |
20-
| `LOGGING_FORMAT` | enum | Logging format: `text`, `json` | `json` | No |
21-
| `CORS_ALLOW_ORIGIN` | string | CORS allow origin header value | `*` | No |
13+
| Variable | Type | Description | Default | Required |
14+
| ---------------------- | ------- | ------------------------------------------------ | ------------------------ | -------- |
15+
| `TASKS_TABLE` | string | The name of the DynamoDB table for storing tasks | - | Yes |
16+
| `TASK_EVENT_TOPIC_ARN` | string | The ARN of the SNS topic for task events | - | Yes |
17+
| `AWS_REGION` | string | The AWS region where resources are deployed | `us-east-1` | No |
18+
| `USE_LOCALSTACK` | boolean | Enable LocalStack mode for local development | `false` | No |
19+
| `LOCALSTACK_ENDPOINT` | string | LocalStack endpoint URL | `http://localstack:4566` | No |
20+
| `LOGGING_ENABLED` | boolean | Enable or disable application logging | `true` | No |
21+
| `LOGGING_LEVEL` | enum | Logging level: `debug`, `info`, `warn`, `error` | `debug` | No |
22+
| `LOGGING_FORMAT` | enum | Logging format: `text`, `json` | `json` | No |
23+
| `CORS_ALLOW_ORIGIN` | string | CORS allow origin header value | `*` | No |
2224

2325
### Usage
2426

@@ -46,18 +48,20 @@ The infrastructure configuration is managed through environment variables prefix
4648

4749
The following environment variables are available for configuring the infrastructure:
4850

49-
| Variable | Type | Description | Default | Required |
50-
| ------------------------- | ------- | ------------------------------------------------------ | ---------------- | -------- |
51-
| `CDK_APP_NAME` | string | The application name used in resource naming | `lambda-starter` | No |
52-
| `CDK_ENV` | enum | Environment: `dev`, `qat`, `prd` | - | Yes |
53-
| `CDK_ACCOUNT` | string | AWS account ID for deployment | - | No |
54-
| `CDK_REGION` | string | AWS region for deployment | - | No |
55-
| `CDK_OU` | string | Organizational Unit for resource tagging | `leanstacks` | No |
56-
| `CDK_OWNER` | string | Owner tag for resource tracking | `unknown` | No |
57-
| `CDK_CORS_ALLOW_ORIGIN` | string | CORS allow origin for API Gateway and Lambda functions | `*` | No |
58-
| `CDK_APP_LOGGING_ENABLED` | boolean | Enable logging in Lambda functions | `true` | No |
59-
| `CDK_APP_LOGGING_LEVEL` | enum | Logging level: `debug`, `info`, `warn`, `error` | `info` | No |
60-
| `CDK_APP_LOGGING_FORMAT` | enum | Logging format: `text`, `json` | `json` | No |
51+
| Variable | Type | Description | Default | Required |
52+
| ------------------------- | ------- | ------------------------------------------------------ | ----------------------- | -------- |
53+
| `CDK_APP_NAME` | string | The application name used in resource naming | `lambda-starter` | No |
54+
| `CDK_ENV` | enum | Environment: `local`, `dev`, `qat`, `prd` | - | Yes |
55+
| `CDK_ACCOUNT` | string | AWS account ID for deployment | - | No |
56+
| `CDK_REGION` | string | AWS region for deployment | - | No |
57+
| `CDK_USE_LOCALSTACK` | boolean | Enable LocalStack mode for local development | `false` | No |
58+
| `CDK_LOCALSTACK_ENDPOINT` | string | LocalStack endpoint URL | `http://localhost:4566` | No |
59+
| `CDK_OU` | string | Organizational Unit for resource tagging | `leanstacks` | No |
60+
| `CDK_OWNER` | string | Owner tag for resource tracking | `unknown` | No |
61+
| `CDK_CORS_ALLOW_ORIGIN` | string | CORS allow origin for API Gateway and Lambda functions | `*` | No |
62+
| `CDK_APP_LOGGING_ENABLED` | boolean | Enable logging in Lambda functions | `true` | No |
63+
| `CDK_APP_LOGGING_LEVEL` | enum | Logging level: `debug`, `info`, `warn`, `error` | `info` | No |
64+
| `CDK_APP_LOGGING_FORMAT` | enum | Logging format: `text`, `json` | `json` | No |
6165

6266
### Usage
6367

@@ -78,18 +82,70 @@ Infrastructure configuration can be provided through:
7882
1. **Environment variables** - Set directly in your shell or CI/CD pipeline
7983
2. **.env file** - Create a `.env` file in the `infrastructure/` directory for local development
8084

81-
Example `.env` file:
85+
Example `.env` file for AWS deployment:
8286

8387
```bash
88+
##################################################
89+
#### Infrastructure Environment Configuration ####
90+
##################################################
91+
92+
### Application Configuration ###
93+
## Application name (default: lambda-starter)
94+
CDK_APP_NAME=lambda-starter
95+
## The infrastructure environment (dev, qat, prd)
8496
CDK_ENV=dev
85-
CDK_ACCOUNT=123456789012
97+
98+
### Resource Tagging Configuration ###
99+
## Organizational Unit (e.g., software-engineering, shared-services)
100+
CDK_OU=software-engineering
101+
## Owner of the infrastructure resources (e.g., team-alpha, Joe Engineer)
102+
CDK_OWNER=microservices-team
103+
104+
### Logging Configuration ###
105+
## Application logging level: debug, info, warn, error (default: info)
106+
CDK_APP_LOGGING_LEVEL=debug
107+
```
108+
109+
Example `.env` file for LocalStack local development:
110+
111+
```bash
112+
##################################################
113+
#### LocalStack Environment Configuration #######
114+
##################################################
115+
116+
### Application Configuration ###
117+
## Application name (default: lambda-starter)
118+
CDK_APP_NAME=lambda-starter
119+
## The infrastructure environment (local for LocalStack)
120+
CDK_ENV=local
121+
122+
### LocalStack Configuration ###
123+
## Enable LocalStack mode
124+
CDK_USE_LOCALSTACK=true
125+
## LocalStack endpoint (default: http://localstack:4566)
126+
CDK_LOCALSTACK_ENDPOINT=http://localstack:4566
127+
128+
### AWS Configuration ###
129+
## AWS Region for LocalStack (default: us-east-1)
86130
CDK_REGION=us-east-1
87-
CDK_OU=leanstacks
88-
CDK_OWNER=platform-team
89-
CDK_CORS_ALLOW_ORIGIN=https://example.com
131+
132+
### Resource Tagging Configuration ###
133+
## Organizational Unit
134+
CDK_OU=software-engineering
135+
## Owner of the infrastructure resources
136+
CDK_OWNER=local-dev
137+
138+
### Logging Configuration ###
139+
## Enable application logging
90140
CDK_APP_LOGGING_ENABLED=true
141+
## Application logging level: debug, info, warn, error
91142
CDK_APP_LOGGING_LEVEL=debug
92-
CDK_APP_LOGGING_FORMAT=json
143+
## Application logging format: text, json (text is easier to read locally)
144+
CDK_APP_LOGGING_FORMAT=text
145+
146+
### CORS Configuration ###
147+
## CORS allow origin for API Gateway (allowing all for local development)
148+
CDK_CORS_ALLOW_ORIGIN=*
93149
```
94150

95151
**Important:** Never commit `.env` files containing sensitive information to source control.
@@ -98,19 +154,30 @@ CDK_APP_LOGGING_FORMAT=json
98154

99155
All AWS resources created by the CDK are automatically tagged with the following tags:
100156

101-
| Tag | Description | Source |
102-
| ------- | ------------------------------ | -------------- |
103-
| `App` | Application name | `CDK_APP_NAME` |
104-
| `Env` | Environment (dev, qat, prd) | `CDK_ENV` |
105-
| `OU` | Organizational Unit | `CDK_OU` |
106-
| `Owner` | Team or individual responsible | `CDK_OWNER` |
157+
| Tag | Description | Source |
158+
| ------- | ---------------------------------- | -------------- |
159+
| `App` | Application name | `CDK_APP_NAME` |
160+
| `Env` | Environment (local, dev, qat, prd) | `CDK_ENV` |
161+
| `OU` | Organizational Unit | `CDK_OU` |
162+
| `Owner` | Team or individual responsible | `CDK_OWNER` |
107163

108164
These tags are used for cost allocation, resource management, and identifying resources in AWS.
109165

110166
### Environment-Specific Settings
111167

112168
Different environments may require different configuration values. Consider these recommendations:
113169

170+
#### LocalStack (local)
171+
172+
- `CDK_ENV=local` - Enables LocalStack mode
173+
- `CDK_USE_LOCALSTACK=true` - Required for LocalStack
174+
- `CDK_LOCALSTACK_ENDPOINT=http://localstack:4566` - LocalStack endpoint (uses Docker container hostname)
175+
- `CDK_APP_LOGGING_LEVEL=debug` - Verbose logging for development
176+
- `CDK_APP_LOGGING_FORMAT=text` - Human-readable logs for local debugging
177+
- `CDK_CORS_ALLOW_ORIGIN=*` - Allow all origins for local testing
178+
- No AWS account required - LocalStack uses mock credentials
179+
- See the [LocalStack Guide](LocalStackGuide.md) for complete setup instructions
180+
114181
#### Development (dev)
115182

116183
- `CDK_APP_LOGGING_LEVEL=debug` - Verbose logging for development
@@ -152,6 +219,8 @@ Infrastructure configuration variables are passed to Lambda functions with modif
152219

153220
| Infrastructure Variable | Lambda Environment Variable |
154221
| ------------------------- | --------------------------- |
222+
| `CDK_USE_LOCALSTACK` | `USE_LOCALSTACK` |
223+
| `CDK_LOCALSTACK_ENDPOINT` | `LOCALSTACK_ENDPOINT` |
155224
| `CDK_APP_LOGGING_ENABLED` | `LOGGING_ENABLED` |
156225
| `CDK_APP_LOGGING_LEVEL` | `LOGGING_LEVEL` |
157226
| `CDK_APP_LOGGING_FORMAT` | `LOGGING_FORMAT` |

‎docs/InfrastructureGuide.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -99,12 +99,12 @@ All Lambda functions receive the following environment variables from the CDK co
9999

100100
All resources are tagged for cost allocation and management:
101101

102-
| Tag | Source | Example Value |
103-
| ------- | -------------- | ------------------- |
104-
| `App` | `CDK_APP_NAME` | `lambda-starter` |
105-
| `Env` | `CDK_ENV` | `dev`, `qat`, `prd` |
106-
| `OU` | `CDK_OU` | `leanstacks` |
107-
| `Owner` | `CDK_OWNER` | `platform-team` |
102+
| Tag | Source | Example Value |
103+
| ------- | -------------- | ---------------------- |
104+
| `App` | `CDK_APP_NAME` | `lambda-starter` |
105+
| `Env` | `CDK_ENV` | `dev`, `qat`, `prd` |
106+
| `OU` | `CDK_OU` | `software-engineering` |
107+
| `Owner` | `CDK_OWNER` | `platform-team` |
108108

109109
---
110110

0 commit comments

Comments
 (0)