Require LocalStack license and standardize sample documentation (#269)

* 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

* trigger CI

* try to run

* Fix auth token guidance and missing prerequisites across all samples

- Update all 48 Makefiles: change error URL from /pricing to
  /workspace/auth-token so users land on the token page directly
- Update all 48 READMEs: expand license bullet to include explicit
  export LOCALSTACK_AUTH_TOKEN=<your-auth-token> instruction with
  a link to the LocalStack Web Application
- Fix apigw-custom-domain/README.md: add missing license bullet,
  Docker, localstack CLI, and awslocal CLI prerequisites; remove
  stale Environment row from the metadata table

* Move auth token setup into Start LocalStack section in all READMEs

- Revert Prerequisites license bullet to simple one-liner (no inline
  code block or web app link)
- Add explicit 'export LOCALSTACK_AUTH_TOKEN=<your-auth-token>' as
  the first command in the Start LocalStack code block across all
  sample READMEs (47 make start + 1 localstack start variant)

* restore DEBUG=1, expected outputs, and missing context

Author: HarshCasper

.github/workflows/test.yml

@@ -36,17 +36,21 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
+
       - name: Install LocalStack
         run: pip install localstack awscli-local[ver1] virtualenv
+
       - name: Setup config
         run: |
           echo "Configuring git for codecommit sample"
           git config --global user.email "localstack.sample@localstack.cloud"
           git config --global user.name "Localstack Pro-Samples"
+
       - name: Pull the latest docker image
         run: docker pull localstack/localstack-pro
-      - name: Execute a simple test
+
+      - name: Execute tests
         timeout-minutes: 10
         run: |
           cd ${{ matrix.directory }}

README.md

@@ -1,6 +1,6 @@
 # LocalStack Pro Samples
 
-This repository contains sample projects that can be deployed on your local machine using [LocalStack Pro](https://localstack.cloud/).
+This repository contains sample projects that can be deployed on your local machine using [LocalStack](https://localstack.cloud/).
 
 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.
 
@@ -14,14 +14,27 @@ Each example in the repository is prefixed with the name of the AWS service bein
 
 ## Configuration
 
-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.
+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:
+
+```bash
+export LOCALSTACK_AUTH_TOKEN=<your-auth-token>
+```
+
+Alternatively, use the LocalStack CLI to persist the token:
+
+```bash
+localstack auth set-token <your-auth-token>
+```
+
+You can find your Auth Token on the [LocalStack Web Application](https://app.localstack.cloud/workspace/auth-token).
 
 ## Outline
 
 | Sample Name                                                    | Description                                                                                        |
 | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
 | [Serverless Websockets](serverless-websockets)                 | API Gateway V2 websocket APIs deployed via the Serverless framework                                |
 | [RDS Database Queries](rds-db-queries)                         | Running queries locally against an RDS database                                                    |
+| [RDS Failover Test](rds-failover-test)                         | Running a failover test against an RDS global cluster                                              |
 | [Neptune Graph Database](neptune-graph-db)                     | Running queries locally against a Neptune Graph database                                           |
 | [Lambda Event Filtering](lambda-event-filtering)               | Lambda event source filtering with DynamoDB and SQS                                                |
 | [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
 | [ECS ECR Container application](ecs-ecr-container-app)         | Pushing Docker images to ECR and running them locally on ECS                                       |
 | [Athena queries over S3](athena-s3-queries)                    | Running Athena queries over S3 files locally                                                       |
 | [Terraform resources](terraform-resources)                     | Deploying various AWS resources via Terraform                                                      |
-| [Lambda Function URLs](lambda-function-urls)                   | Invoking Lambda functions via HTTP(s) URLs                                                         |
+| [CDK for Terraform resources](cdk-for-terraform)               | Deploying AWS resources via CDK for Terraform                                                      |
+| [Lambda Function URLs (JavaScript)](lambda-function-urls-javascript) | Invoking Lambda functions via HTTP(S) URLs using JavaScript                               |
+| [Lambda Function URLs (Python)](lambda-function-urls-python)   | Invoking Lambda functions via HTTP(S) URLs using Python                                            |
 | [Sagemaker inference](sagemaker-inference)                     | Creating & invoking a Sagemaker endpoint locally with MNIST dataset                                |
 | [MSK with Glue Schema Registry](glue-msk-schema-registry)      | Use of MSK, Glue Schema Registry, Glue ETL, and RDS                                                |
 | [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
 | [ELB Load Balancing](elb-load-balancing)                       | Using ELBv2 Application Load Balancers locally, deployed via the Serverless framework              |
 | [Reproducible ML](reproducible-ml)                             | Train, save and evaluate a scikit-learn machine learning model using AWS Lambda and S3             |
 | [Lambda PHP/Bref CDK App](lambda-php-bref-cdk-app)             | Running PHP/Bref Lambda handler locally, deployed via AWS CDK                                      |
+| [Step Functions with Lambda](stepfunctions-lambda)             | Orchestrating Lambda functions using AWS Step Functions                                            |
+| [Multi-Account S3 Access](multi-account-multi-region-s3-access) | Accessing S3 resources across different AWS accounts and regions                                  |
+| [Route53 DNS Failover](route53-dns-failover)                   | Route53 DNS failover based on health checks                                                        |
+| [EMR Serverless Sample](emr-serverless-sample)                 | Running EMR Serverless jobs locally                                                                |
+| [EMR Serverless Spark](emr-serverless-spark)                   | Running Java Spark jobs on EMR Serverless                                                          |
+| [EMR Serverless Python Dependencies](emr-serverless-python-dependencies) | Adding Python dependencies to EMR Serverless PySpark jobs                              |
+| [Testcontainers Java Sample](testcontainers-java-sample)       | Using LocalStack Testcontainers with RDS in Java                                                   |
 
 ## Checking out a single sample
 
@@ -104,6 +126,7 @@ run:         ## Run the actual sample steps/commands. This assumes LocalStack is
         ./run.sh
 
 start:       ## Start LocalStack in detached mode
+        @test -n "${LOCALSTACK_AUTH_TOKEN}" || (echo "LOCALSTACK_AUTH_TOKEN is not set. Get your auth token at https://localstack.cloud/pricing."; exit 1)
         localstack start -d
 
 stop:        ## Stop the Running LocalStack container
@@ -117,9 +140,9 @@ ready:       ## Make sure the LocalStack container is up
 logs:        ## Save the logs in a separate file, since the LS container will only contain the logs of the last sample run.
         @localstack logs > logs.txt
 
-test-ci:     ## Execute the necessary targets in the correct order for an automatic execution. 
+test-ci:     ## Execute the necessary targets in the correct order for an automatic execution.
         make start install ready run; return_code=`echo $$?`;\
         make logs; make stop; exit $$return_code;
 
 .PHONY: usage install run start stop ready logs test-ci
-```
+```

apigw-custom-domain/Makefile

@@ -55,7 +55,8 @@ test:        ## Run tests
 	make deploy run target=ci
 
 start:       ## Start LocalStack
-	ACTIVATE_PRO=1 localstack start -d
+	@test -n "${LOCALSTACK_AUTH_TOKEN}" || (echo "LOCALSTACK_AUTH_TOKEN is not set. Find your token at https://app.localstack.cloud/workspace/auth-token"; exit 1)
+	localstack start -d
 
 stop:        ## Stop LocalStack
 	@echo

apigw-custom-domain/README.md

@@ -2,7 +2,6 @@
 
 | Key          | Value                             |
 | ------------ | --------------------------------- |
-| Environment  | LocalStack                        |
 | Services     | API Gateway, Lambda, Route53, ACM |
 | Integrations | Serverless Framework              |
 | Categories   | Serverless; REST API              |
@@ -15,9 +14,13 @@ Under the hood, the Serverless framework uses the [`serverless-localstack`](http
 
 ## Prerequisites
 
-* [Node.js 18.x](https://nodejs.org/en/download/package-manager) with `npm`
-* [Serverless Framework](https://www.serverless.com/framework/docs/getting-started) 3.x
-* `openssl`
+- 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.
+- [Docker](https://docs.docker.com/get-docker/)
+- [`localstack` CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli)
+- [`awslocal` CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/)
+- [Node.js 18.x](https://nodejs.org/en/download/package-manager) with `npm`
+- [Serverless Framework](https://www.serverless.com/framework/docs/getting-started) 3.x
+- `openssl`
 
 ## Check prerequisites
 
@@ -34,6 +37,7 @@ make install
 ## Start LocalStack
 
 ```bash
+export LOCALSTACK_AUTH_TOKEN=<your-auth-token>
 make start
 ```
 

appsync-graphql-api/Makefile

@@ -7,6 +7,15 @@ SHELL := /bin/bash
 usage:       ## Show this help
 	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
 
+check:    ## Check if all required prerequisites are installed
+	@command -v docker > /dev/null 2>&1 || { echo "Docker is not installed. Please install Docker and try again."; exit 1; }
+	@command -v node > /dev/null 2>&1 || { echo "Node.js is not installed. Please install Node.js and try again."; exit 1; }
+	@command -v python3 > /dev/null 2>&1 || { echo "Python 3 is not installed. Please install Python 3 and try again."; exit 1; }
+	@command -v localstack > /dev/null 2>&1 || { echo "LocalStack CLI is not installed. Please install it and try again."; exit 1; }
+	@command -v awslocal > /dev/null 2>&1 || { echo "awslocal is not installed. Please run: pip install awscli-local"; exit 1; }
+	@echo "All required prerequisites are available."
+
+
 install:     ## Install dependencies
 	@test -e node_modules || npm install
 	@which serverless || npm install -g serverless
@@ -17,7 +26,8 @@ install:     ## Install dependencies
 run:         ## Deploy the app locally and run an AppSync GraphQL test invocation
 	./run.sh
 start:
-	localstack start -d
+	@test -n "${LOCALSTACK_AUTH_TOKEN}" || (echo "LOCALSTACK_AUTH_TOKEN is not set. Find your token at https://app.localstack.cloud/workspace/auth-token"; exit 1)
+	DEBUG=1 LOCALSTACK_AUTH_TOKEN=$(LOCALSTACK_AUTH_TOKEN) localstack start -d
 
 stop:
 	@echo

appsync-graphql-api/README.md

@@ -1,51 +1,68 @@
-# LocalStack Demo: AppSync GraphQL APIs for DynamoDB and RDS Aurora Postgres
+# AppSync GraphQL API
 
-Simple demo application illustrating how to proxy data from different resources (DynamoDB tables, RDS databases) via AppSync GraphQL using LocalStack.
+| Key          | Value                               |
+| ------------ | ----------------------------------- |
+| Services     | AppSync, DynamoDB, RDS              |
+| Integrations | AWS SDK, AWS CLI                    |
+| Categories   | GraphQL; Serverless                 |
+
+## Introduction
+
+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.
 
 ## Prerequisites
 
-* LocalStack
-* Docker
-* Python 3.6+
-* `make`
+- 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.
+- [Docker](https://docs.docker.com/get-docker/)
+- [`localstack` CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli)
+- [`awslocal` CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/)
+- [Python 3](https://www.python.org/downloads/)
 
-## Installing
+## Check prerequisites
 
-To install the dependencies:
+```bash
+make check
 ```
+
+## Installation
+
+```bash
 make install
 ```
 
-## Starting LocalStack
+## Start LocalStack
 
-Make sure that LocalStack is started:
-```
-LOCALSTACK_AUTH_TOKEN=... DEBUG=1 localstack start
+```bash
+export LOCALSTACK_AUTH_TOKEN=<your-auth-token>
+make start
 ```
 
-## Running
+## Run the application
 
-Deploy the app locally and run the GraphQL test invocations:
-```
+```bash
 make run
 ```
 
-The demo will run different GraphQL queries, for two different datasources (DynamoDB / RDS Aurora):
+The script:
 
-1. a mutation query which inserts a new item into DynamoDB / RDS Aurora
-2. a query which scans and returns the items from DynamoDB / RDS Aurora
+- Deploys AppSync GraphQL API with DynamoDB and RDS Aurora Postgres resolvers.
+- Runs mutation queries to insert items into both data sources.
+- Runs query operations to scan and return items from DynamoDB and RDS Aurora.
+- Connects a WebSocket client to verify real-time subscription notifications.
 
 You should see a success output in the terminal:
-```
+
+```bash
 {"data":{"addPostDDB":{"id":{"S":"id123"}}}}
 {"data":{"getPostsDDB":[{"id":{"S":"id123"}}]}}
 ...
 {"data":{"addPostRDS":{"id":{"S":"id123"}}}}
 {"data":{"getPostsRDS":[{"id":{"S":"id123"}}]}}
 ```
 
-... and the item should have been added to your local DynamoDB table (as well as your RDS database):
-```
+The item should also have been added to your local DynamoDB table:
+
+```bash
 $ awslocal dynamodb scan --table-name table1
 {
     "Items": [
@@ -61,9 +78,9 @@ $ awslocal dynamodb scan --table-name table1
 }
 ```
 
-Finally, you should also see a message printed from the WebSocket client subscribed to notifications from the API:
-```
-...
+Finally, you should see a notification from the WebSocket client:
+
+```bash
 Starting a WebSocket client to subscribe to GraphQL mutation operations.
 Connecting to WebSocket URL ws://localhost:4510/graphql/...
 ...

athena-s3-queries/Makefile

@@ -6,6 +6,13 @@ export AWS_DEFAULT_REGION=us-east-1
 usage:       ## Show this help
 	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
 
+check:    ## Check if all required prerequisites are installed
+	@command -v docker > /dev/null 2>&1 || { echo "Docker is not installed. Please install Docker and try again."; exit 1; }
+	@command -v localstack > /dev/null 2>&1 || { echo "LocalStack CLI is not installed. Please install it and try again."; exit 1; }
+	@command -v awslocal > /dev/null 2>&1 || { echo "awslocal is not installed. Please run: pip install awscli-local"; exit 1; }
+	@echo "All required prerequisites are available."
+
+
 install:     ## Install dependencies
 #	@test -e node_modules || npm install
 	@which localstack || pip install localstack
@@ -16,7 +23,8 @@ run:         ## Set up database connections and run Athena queries locally
 		echo "Running Athena queries"; \
 		./run.sh
 start:
-	localstack start -d
+	@test -n "${LOCALSTACK_AUTH_TOKEN}" || (echo "LOCALSTACK_AUTH_TOKEN is not set. Find your token at https://app.localstack.cloud/workspace/auth-token"; exit 1)
+	DEBUG=1 LOCALSTACK_AUTH_TOKEN=$(LOCALSTACK_AUTH_TOKEN) localstack start -d
 
 stop:
 	@echo

athena-s3-queries/README.md

@@ -1,43 +1,57 @@
-# LocalStack Demo: Athena Queries over S3 Files
+# Athena Queries over S3 Files
 
-Simple demo application illustrating how to run Athena queries over S3 files locally, using LocalStack.
+| Key          | Value                          |
+| ------------ | ------------------------------ |
+| Services     | Athena, S3                     |
+| Integrations | AWS CLI                        |
+| Categories   | Analytics; Serverless          |
+
+## Introduction
+
+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.
 
 ## Prerequisites
 
-* LocalStack
-* Docker
-* Node.js / `npm`
-* `make`
+- 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.
+- [Docker](https://docs.docker.com/get-docker/)
+- [`localstack` CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli)
+- [`awslocal` CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/)
+- [Node.js](https://nodejs.org/en/download/) with `npm`
 
-## Installing
+## Check prerequisites
 
-To install the dependencies:
+```bash
+make check
 ```
+
+## Installation
+
+```bash
 make install
 ```
 
-## Starting LocalStack
+## Start LocalStack
 
-Make sure that LocalStack is started:
-```
-LOCALSTACK_AUTH_TOKEN=... DEBUG=1 localstack start
+```bash
+export LOCALSTACK_AUTH_TOKEN=<your-auth-token>
+make start
 ```
 
-## Running
+## Run the application
 
-Start the app locally and run the Athena test queries:
-```
+```bash
 make run
 ```
 
-The demo script performs the following actions:
+The script:
+
+- Creates an S3 bucket and uploads CSV test data (person details) to the bucket.
+- Runs queries to create Athena database and table metadata.
+- Executes a SELECT query to count users by gender.
+- Downloads and displays the query results from the S3 results bucket.
 
-1. Create an S3 bucket and upload test data (CSV files with person details) to the bucket
-2. Run queries to create the table metadata in Athena
-3. Running a simple query over the test file - querying the number of users by gender (male/female)
-4. Downloading the query results from the S3 results bucket
+You should see output similar to:
 
-You should see something similar to the following log output in the terminal:
 ```
 $ ./run.sh
 Uploading test data to S3...
@@ -46,8 +60,6 @@ upload: data/data.csv to s3://athena-test/data/data.csv
 Running queries to create database and table definitions...
 NOTE: This can take a very long time (several minutes) as the system is initializing
 Waiting for completion status of query cda0572a: RUNNING
-Waiting for completion status of query cda0572a: RUNNING
-Waiting for completion status of query cda0572a: RUNNING
 ...
 Waiting for completion status of query cda0572a: SUCCEEDED
 Starting SELECT query over data in S3. Query ID: 8a19e3a3