LocalStack Pro Samples

This repository contains sample projects that can be deployed on your local machine using LocalStack Pro.

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.

Prerequisites

• Docker
• awslocal CLI
• Serverless
• Terraform
• make & jq

Configuration

Some of the samples require LocalStack Pro features. Please make sure to properly configure the LOCALSTACK_API_KEY environment variable. You can find your API key in the LocalStack Pro dashboard and you can refer to our API key documentation for more details.

Outline

Checking out a single sample

To check out a single sample, you can use the following commands:

mkdir localstack-samples && cd localstack-samples
git init
git remote add origin -f [email protected]:localstack/localstack-pro-samples.git
git config core.sparseCheckout true
echo <LOCALSTACK_SAMPLE_DIRECTORY_NAME> >> .git/info/sparse-checkout
git pull origin master

The above commands use sparse-checkout to only pull the sample you are interested in. You can find the name of the sample directory in the table above.

Developer Notes

Makefiles for samples

All samples should have a Makefile to unify the execution of the otherwise heterogeneous samples. It needs to fulfill two criteria:

• The sample should be executable independently, since it can be checked out on its own (see Checking out a single sample).
• It should contain a test-ci target to be executed automatically within the CI pipeline. This step needs to take care of all infrastructure tasks (starting/stopping/logs/etc) in addition to any sample commands executed.

A typical Makefile looks like this:

export AWS_ACCESS_KEY_ID ?= test
export AWS_SECRET_ACCESS_KEY ?= test
export AWS_DEFAULT_REGION=us-east-1
SHELL := /bin/bash

usage:       ## Show this help
        @fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'

install:     ## Install dependencies
        @which localstack || pip install localstack
        @which awslocal || pip install awscli-local
        ## install whatever else you need, like node modules, python packages, etc.
        @test -e node_modules || npm install
        @test -e .venv || (python3 -m venv .venv; source .venv/bin/activate; pip install -r requirements.txt)

run:         ## Run the actual sample steps/commands. This assumes LocalStack is up and running.
        ./run.sh

start:       ## Start LocalStack in detached mode
        localstack start -d

stop:        ## Stop the Running LocalStack container
        @echo
        localstack stop

ready:       ## Make sure the LocalStack container is up
        @echo Waiting on the LocalStack container...
        @localstack wait -t 30 && echo LocalStack is ready to use! || (echo Gave up waiting on LocalStack, exiting. && exit 1)

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. 
        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