Skip to content

Commit a2c239a

Browse files
HarshCasperHarshCasper
committed
Require LocalStack license and standardize documentation across all samples
- Add LOCALSTACK_AUTH_TOKEN check to all `start` Makefile targets - Remove deprecated ACTIVATE_PRO=1 from all Makefiles - Add `check` target for prerequisite validation to all Makefiles - Create Makefiles for 11 samples that were missing them - Rewrite all sample READMEs to match gold standard format with key/value tables - Add license prerequisite as first bullet in all READMEs - Create missing READMEs for cdk-for-terraform, emr-serverless-sample, lambda-function-urls-python, lambda-hot-reloading, lambda-xray - Update root README Configuration section and add 11 missing table entries - Fix broken lambda-function-urls link in root README
1 parent 6eda9cf commit a2c239a

97 files changed

Lines changed: 2560 additions & 1671 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# LocalStack Pro Samples
22

3-
This repository contains sample projects that can be deployed on your local machine using [LocalStack Pro](https://localstack.cloud/).
3+
This repository contains sample projects that can be deployed on your local machine using [LocalStack](https://localstack.cloud/).
44

55
Each example in the repository is prefixed with the name of the AWS service being used. For example, the `elb-load-balancing` directory contains examples that demonstrate how to use the Elastic Load Balancing service with LocalStack. Please refer to the sub directories for more details and instructions on how to start the samples.
66

@@ -14,14 +14,27 @@ Each example in the repository is prefixed with the name of the AWS service bein
1414

1515
## Configuration
1616

17-
Some of the samples require LocalStack Pro features. Please make sure to properly configure the `LOCALSTACK_AUTH_TOKEN` environment variable. You can find your Auth Token on the [LocalStack Web Application](https://app.localstack.cloud/workspace/auth-token) and you can refer to our [Auth Token documentation](https://docs.localstack.cloud/getting-started/auth-token/) for more details.
17+
All samples require a valid [LocalStack for AWS license](https://localstack.cloud/pricing). Your license provides a [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) to activate LocalStack. Set it before running any sample:
18+
19+
```bash
20+
export LOCALSTACK_AUTH_TOKEN=<your-auth-token>
21+
```
22+
23+
Alternatively, use the LocalStack CLI to persist the token:
24+
25+
```bash
26+
localstack auth set-token <your-auth-token>
27+
```
28+
29+
You can find your Auth Token on the [LocalStack Web Application](https://app.localstack.cloud/workspace/auth-token).
1830

1931
## Outline
2032

2133
| Sample Name | Description |
2234
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
2335
| [Serverless Websockets](serverless-websockets) | API Gateway V2 websocket APIs deployed via the Serverless framework |
2436
| [RDS Database Queries](rds-db-queries) | Running queries locally against an RDS database |
37+
| [RDS Failover Test](rds-failover-test) | Running a failover test against an RDS global cluster |
2538
| [Neptune Graph Database](neptune-graph-db) | Running queries locally against a Neptune Graph database |
2639
| [Lambda Event Filtering](lambda-event-filtering) | Lambda event source filtering with DynamoDB and SQS |
2740
| [Glacier & S3 select queries](glacier-s3-select) | Using Glacier API and running S3 Select queries locally |
@@ -42,7 +55,9 @@ Some of the samples require LocalStack Pro features. Please make sure to properl
4255
| [ECS ECR Container application](ecs-ecr-container-app) | Pushing Docker images to ECR and running them locally on ECS |
4356
| [Athena queries over S3](athena-s3-queries) | Running Athena queries over S3 files locally |
4457
| [Terraform resources](terraform-resources) | Deploying various AWS resources via Terraform |
45-
| [Lambda Function URLs](lambda-function-urls) | Invoking Lambda functions via HTTP(s) URLs |
58+
| [CDK for Terraform resources](cdk-for-terraform) | Deploying AWS resources via CDK for Terraform |
59+
| [Lambda Function URLs (JavaScript)](lambda-function-urls-javascript) | Invoking Lambda functions via HTTP(S) URLs using JavaScript |
60+
| [Lambda Function URLs (Python)](lambda-function-urls-python) | Invoking Lambda functions via HTTP(S) URLs using Python |
4661
| [Sagemaker inference](sagemaker-inference) | Creating & invoking a Sagemaker endpoint locally with MNIST dataset |
4762
| [MSK with Glue Schema Registry](glue-msk-schema-registry) | Use of MSK, Glue Schema Registry, Glue ETL, and RDS |
4863
| [AppSync GraphQL](appsync-graphql-api) | Deploying a GraphQL API using AppSync |
@@ -59,6 +74,13 @@ Some of the samples require LocalStack Pro features. Please make sure to properl
5974
| [ELB Load Balancing](elb-load-balancing) | Using ELBv2 Application Load Balancers locally, deployed via the Serverless framework |
6075
| [Reproducible ML](reproducible-ml) | Train, save and evaluate a scikit-learn machine learning model using AWS Lambda and S3 |
6176
| [Lambda PHP/Bref CDK App](lambda-php-bref-cdk-app) | Running PHP/Bref Lambda handler locally, deployed via AWS CDK |
77+
| [Step Functions with Lambda](stepfunctions-lambda) | Orchestrating Lambda functions using AWS Step Functions |
78+
| [Multi-Account S3 Access](multi-account-multi-region-s3-access) | Accessing S3 resources across different AWS accounts and regions |
79+
| [Route53 DNS Failover](route53-dns-failover) | Route53 DNS failover based on health checks |
80+
| [EMR Serverless Sample](emr-serverless-sample) | Running EMR Serverless jobs locally |
81+
| [EMR Serverless Spark](emr-serverless-spark) | Running Java Spark jobs on EMR Serverless |
82+
| [EMR Serverless Python Dependencies](emr-serverless-python-dependencies) | Adding Python dependencies to EMR Serverless PySpark jobs |
83+
| [Testcontainers Java Sample](testcontainers-java-sample) | Using LocalStack Testcontainers with RDS in Java |
6284

6385
## Checking out a single sample
6486

@@ -104,6 +126,7 @@ run: ## Run the actual sample steps/commands. This assumes LocalStack is
104126
./run.sh
105127

106128
start: ## Start LocalStack in detached mode
129+
@test -n "${LOCALSTACK_AUTH_TOKEN}" || (echo "LOCALSTACK_AUTH_TOKEN is not set. Get your auth token at https://localstack.cloud/pricing."; exit 1)
107130
localstack start -d
108131

109132
stop: ## Stop the Running LocalStack container
@@ -117,9 +140,9 @@ ready: ## Make sure the LocalStack container is up
117140
logs: ## Save the logs in a separate file, since the LS container will only contain the logs of the last sample run.
118141
@localstack logs > logs.txt
119142

120-
test-ci: ## Execute the necessary targets in the correct order for an automatic execution.
143+
test-ci: ## Execute the necessary targets in the correct order for an automatic execution.
121144
make start install ready run; return_code=`echo $$?`;\
122145
make logs; make stop; exit $$return_code;
123146

124147
.PHONY: usage install run start stop ready logs test-ci
125-
```
148+
```

‎apigw-custom-domain/Makefile‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,8 @@ test: ## Run tests
5555
make deploy run target=ci
5656

5757
start: ## Start LocalStack
58-
ACTIVATE_PRO=1 localstack start -d
58+
@test -n "${LOCALSTACK_AUTH_TOKEN}" || (echo "LOCALSTACK_AUTH_TOKEN is not set. Get your auth token at https://localstack.cloud/pricing."; exit 1)
59+
localstack start -d
5960

6061
stop: ## Stop LocalStack
6162
@echo

‎appsync-graphql-api/Makefile‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@ SHELL := /bin/bash
77
usage: ## Show this help
88
@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
99

10+
check: ## Check if all required prerequisites are installed
11+
@command -v docker > /dev/null 2>&1 || { echo "Docker is not installed. Please install Docker and try again."; exit 1; }
12+
@command -v node > /dev/null 2>&1 || { echo "Node.js is not installed. Please install Node.js and try again."; exit 1; }
13+
@command -v python3 > /dev/null 2>&1 || { echo "Python 3 is not installed. Please install Python 3 and try again."; exit 1; }
14+
@command -v localstack > /dev/null 2>&1 || { echo "LocalStack CLI is not installed. Please install it and try again."; exit 1; }
15+
@command -v awslocal > /dev/null 2>&1 || { echo "awslocal is not installed. Please run: pip install awscli-local"; exit 1; }
16+
@echo "All required prerequisites are available."
17+
18+
1019
install: ## Install dependencies
1120
@test -e node_modules || npm install
1221
@which serverless || npm install -g serverless
@@ -17,6 +26,7 @@ install: ## Install dependencies
1726
run: ## Deploy the app locally and run an AppSync GraphQL test invocation
1827
./run.sh
1928
start:
29+
@test -n "${LOCALSTACK_AUTH_TOKEN}" || (echo "LOCALSTACK_AUTH_TOKEN is not set. Get your auth token at https://localstack.cloud/pricing."; exit 1)
2030
localstack start -d
2131

2232
stop:

‎appsync-graphql-api/README.md‎

Lines changed: 32 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,53 @@
1-
# LocalStack Demo: AppSync GraphQL APIs for DynamoDB and RDS Aurora Postgres
1+
# AppSync GraphQL API
22

3-
Simple demo application illustrating how to proxy data from different resources (DynamoDB tables, RDS databases) via AppSync GraphQL using LocalStack.
3+
| Key | Value |
4+
| ------------ | ----------------------------------- |
5+
| Services | AppSync, DynamoDB, RDS |
6+
| Integrations | AWS SDK, AWS CLI |
7+
| Categories | GraphQL; Serverless |
8+
9+
## Introduction
10+
11+
A demo application illustrating how to proxy data from different resources (DynamoDB tables, RDS Aurora Postgres databases) via AppSync GraphQL using LocalStack. The sample runs mutation and query operations for two data sources and demonstrates real-time notifications via WebSocket subscriptions.
412

513
## Prerequisites
614

7-
* LocalStack
8-
* Docker
9-
* Python 3.6+
10-
* `make`
15+
- A valid [LocalStack for AWS license](https://localstack.cloud/pricing). Your license provides a [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) to activate LocalStack.
16+
- [Docker](https://docs.docker.com/get-docker/)
17+
- [`localstack` CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli)
18+
- [`awslocal` CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/)
19+
- [Python 3](https://www.python.org/downloads/)
1120

12-
## Installing
21+
## Check prerequisites
1322

14-
To install the dependencies:
15-
```
16-
make install
23+
```bash
24+
make check
1725
```
1826

19-
## Starting LocalStack
27+
## Installation
2028

21-
Make sure that LocalStack is started:
22-
```
23-
LOCALSTACK_AUTH_TOKEN=... DEBUG=1 localstack start
29+
```bash
30+
make install
2431
```
2532

26-
## Running
33+
## Start LocalStack
2734

28-
Deploy the app locally and run the GraphQL test invocations:
29-
```
30-
make run
35+
```bash
36+
make start
3137
```
3238

33-
The demo will run different GraphQL queries, for two different datasources (DynamoDB / RDS Aurora):
39+
## Run the application
3440

35-
1. a mutation query which inserts a new item into DynamoDB / RDS Aurora
36-
2. a query which scans and returns the items from DynamoDB / RDS Aurora
37-
38-
You should see a success output in the terminal:
39-
```
40-
{"data":{"addPostDDB":{"id":{"S":"id123"}}}}
41-
{"data":{"getPostsDDB":[{"id":{"S":"id123"}}]}}
42-
...
43-
{"data":{"addPostRDS":{"id":{"S":"id123"}}}}
44-
{"data":{"getPostsRDS":[{"id":{"S":"id123"}}]}}
41+
```bash
42+
make run
4543
```
4644

47-
... and the item should have been added to your local DynamoDB table (as well as your RDS database):
48-
```
49-
$ awslocal dynamodb scan --table-name table1
50-
{
51-
"Items": [
52-
{
53-
"id": {
54-
"S": "id123"
55-
}
56-
}
57-
],
58-
"Count": 1,
59-
"ScannedCount": 1,
60-
"ConsumedCapacity": null
61-
}
62-
```
45+
The script:
6346

64-
Finally, you should also see a message printed from the WebSocket client subscribed to notifications from the API:
65-
```
66-
...
67-
Starting a WebSocket client to subscribe to GraphQL mutation operations.
68-
Connecting to WebSocket URL ws://localhost:4510/graphql/...
69-
...
70-
Received notification message from WebSocket: {"addedPost": {"id": "id123"}}
71-
```
47+
- Deploys AppSync GraphQL API with DynamoDB and RDS Aurora Postgres resolvers.
48+
- Runs mutation queries to insert items into both data sources.
49+
- Runs query operations to scan and return items from DynamoDB and RDS Aurora.
50+
- Connects a WebSocket client to verify real-time subscription notifications.
7251

7352
## License
7453

‎athena-s3-queries/Makefile‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ export AWS_DEFAULT_REGION=us-east-1
66
usage: ## Show this help
77
@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
88

9+
check: ## Check if all required prerequisites are installed
10+
@command -v docker > /dev/null 2>&1 || { echo "Docker is not installed. Please install Docker and try again."; exit 1; }
11+
@command -v localstack > /dev/null 2>&1 || { echo "LocalStack CLI is not installed. Please install it and try again."; exit 1; }
12+
@command -v awslocal > /dev/null 2>&1 || { echo "awslocal is not installed. Please run: pip install awscli-local"; exit 1; }
13+
@echo "All required prerequisites are available."
14+
15+
916
install: ## Install dependencies
1017
# @test -e node_modules || npm install
1118
@which localstack || pip install localstack
@@ -16,6 +23,7 @@ run: ## Set up database connections and run Athena queries locally
1623
echo "Running Athena queries"; \
1724
./run.sh
1825
start:
26+
@test -n "${LOCALSTACK_AUTH_TOKEN}" || (echo "LOCALSTACK_AUTH_TOKEN is not set. Get your auth token at https://localstack.cloud/pricing."; exit 1)
1927
localstack start -d
2028

2129
stop:

‎athena-s3-queries/README.md‎

Lines changed: 32 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,53 @@
1-
# LocalStack Demo: Athena Queries over S3 Files
1+
# Athena Queries over S3 Files
22

3-
Simple demo application illustrating how to run Athena queries over S3 files locally, using LocalStack.
3+
| Key | Value |
4+
| ------------ | ------------------------------ |
5+
| Services | Athena, S3 |
6+
| Integrations | AWS CLI |
7+
| Categories | Analytics; Serverless |
8+
9+
## Introduction
10+
11+
A demo application illustrating how to run Athena queries over S3 files locally using LocalStack. The sample uploads CSV test data to S3, creates Athena table metadata, and runs SQL queries to aggregate results — all without connecting to AWS.
412

513
## Prerequisites
614

7-
* LocalStack
8-
* Docker
9-
* Node.js / `npm`
10-
* `make`
15+
- A valid [LocalStack for AWS license](https://localstack.cloud/pricing). Your license provides a [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) to activate LocalStack.
16+
- [Docker](https://docs.docker.com/get-docker/)
17+
- [`localstack` CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli)
18+
- [`awslocal` CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/)
19+
- [Node.js](https://nodejs.org/en/download/) with `npm`
1120

12-
## Installing
21+
## Check prerequisites
1322

14-
To install the dependencies:
23+
```bash
24+
make check
1525
```
26+
27+
## Installation
28+
29+
```bash
1630
make install
1731
```
1832

19-
## Starting LocalStack
33+
## Start LocalStack
2034

21-
Make sure that LocalStack is started:
22-
```
23-
LOCALSTACK_AUTH_TOKEN=... DEBUG=1 localstack start
35+
```bash
36+
make start
2437
```
2538

26-
## Running
39+
## Run the application
2740

28-
Start the app locally and run the Athena test queries:
29-
```
41+
```bash
3042
make run
3143
```
3244

33-
The demo script performs the following actions:
34-
35-
1. Create an S3 bucket and upload test data (CSV files with person details) to the bucket
36-
2. Run queries to create the table metadata in Athena
37-
3. Running a simple query over the test file - querying the number of users by gender (male/female)
38-
4. Downloading the query results from the S3 results bucket
45+
The script:
3946

40-
You should see something similar to the following log output in the terminal:
41-
```
42-
$ ./run.sh
43-
Uploading test data to S3...
44-
make_bucket: athena-test
45-
upload: data/data.csv to s3://athena-test/data/data.csv
46-
Running queries to create database and table definitions...
47-
NOTE: This can take a very long time (several minutes) as the system is initializing
48-
Waiting for completion status of query cda0572a: RUNNING
49-
Waiting for completion status of query cda0572a: RUNNING
50-
Waiting for completion status of query cda0572a: RUNNING
51-
...
52-
Waiting for completion status of query cda0572a: SUCCEEDED
53-
Starting SELECT query over data in S3. Query ID: 8a19e3a3
54-
S3 query output location: s3://athena-test/results/Unsaved/2020/02/18/8a19e3a3
55-
Waiting for query results to become available in S3 (this can take some time)
56-
download: s3://athena-test/results/Unsaved/2020/02/18/8a19e3a3/results.csv to /tmp/8a19e3a3.results.csv
57-
Query result downloaded from S3:
58-
Male,49
59-
Female,51
60-
```
47+
- Creates an S3 bucket and uploads CSV test data (person details) to the bucket.
48+
- Runs queries to create Athena database and table metadata.
49+
- Executes a SELECT query to count users by gender.
50+
- Downloads and displays the query results from the S3 results bucket.
6151

6252
## License
6353

‎cdk-for-terraform/Makefile‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
export AWS_ACCESS_KEY_ID ?= test
2+
export AWS_SECRET_ACCESS_KEY ?= test
3+
export AWS_DEFAULT_REGION ?= us-east-1
4+
SHELL := /bin/bash
5+
6+
usage: ## Show this help
7+
@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
8+
9+
check: ## Check if all required prerequisites are installed
10+
@command -v docker > /dev/null 2>&1 || { echo "Docker is not installed. Please install Docker and try again."; exit 1; }
11+
@command -v localstack > /dev/null 2>&1 || { echo "LocalStack CLI is not installed. Please install it and try again."; exit 1; }
12+
@command -v terraform > /dev/null 2>&1 || { echo "Terraform is not installed. Please install Terraform and try again."; exit 1; }
13+
@command -v cdktf > /dev/null 2>&1 || { echo "cdktf is not installed. Please install it and try again."; exit 1; }
14+
@command -v pipenv > /dev/null 2>&1 || { echo "pipenv is not installed. Please run: pip install pipenv"; exit 1; }
15+
@echo "All required prerequisites are available."
16+
17+
install: ## Install dependencies
18+
@cd python && pipenv install
19+
@cd python && cdktf get
20+
21+
start: ## Start LocalStack
22+
@test -n "${LOCALSTACK_AUTH_TOKEN}" || (echo "LOCALSTACK_AUTH_TOKEN is not set. Get your auth token at https://localstack.cloud/pricing."; exit 1)
23+
localstack start -d
24+
25+
stop: ## Stop LocalStack
26+
@echo
27+
localstack stop
28+
29+
ready: ## Wait until LocalStack is ready
30+
@echo Waiting on the LocalStack container...
31+
@localstack wait -t 30 && echo LocalStack is ready to use! || (echo Gave up waiting on LocalStack, exiting. && exit 1)
32+
33+
logs: ## Retrieve LocalStack logs
34+
@localstack logs > logs.txt
35+
36+
deploy: ## Deploy CDK for Terraform stack
37+
@cd python && cdktf deploy --auto-approve
38+
39+
run: ## Run the deployed stack (alias for deploy)
40+
make deploy
41+
42+
test-ci: ## Run CI tests
43+
make check start install ready deploy; return_code=`echo $$?`;\
44+
make logs; make stop; exit $$return_code;
45+
46+
.PHONY: usage check install start stop ready logs deploy run test-ci

0 commit comments

Comments
 (0)