LocalStack - A fully functional local AWS cloud stack

LocalStack provides an easy-to-use test/mocking framework for developing Cloud applications.

Currently, the focus is primarily on supporting the AWS cloud stack.

Announcements

• 2020-09-15: A major (breaking) change has been merged in PR #2905 - starting with releases after v0.11.5, all services are now exposed via the edge service (port 4566) only! Please update your client configurations to use this new endpoint.
• 2019-10-09: LocalStack Pro is out! We're incredibly excited to announce the launch of LocalStack Pro - the enterprise version of LocalStack with additional APIs and advanced features. Check out the free trial at https://localstack.cloud
• 2018-01-10: Help wanted! Please fill out this survey to support a research study on the usage of Serverless and Function-as-a-Service (FaaS) services, conducted at the Chalmers University of Technology. The survey only takes 5-10 minutes of your time. Many thanks for your participation!!
  • The result from this study can be found here
• 2017-08-27: We need your support! LocalStack is growing fast, we now have thousands of developers using the platform regularly. Last month we have recorded a staggering 100k test runs, with 25k+ DynamoDB tables, 20k+ SQS queues, 15k+ Kinesis streams, 13k+ S3 buckets, and 10k+ Lambda functions created locally - for 0$ costs (more details to be published soon). Bug and feature requests are pouring in, and we now need some support from you to keep the open-source version actively maintained. Please check out Open Collective and become a backer or supporter of the project today! Thanks, everybody for contributing. ♥
• 2017-07-20: Please note: Starting with version 0.7.0, the Docker image will be pushed and kept up to date under the new name localstack/localstack. (This means that you may have to update your CI configurations.) Please refer to the updated End-User License Agreement (EULA) for the new versions. The old Docker image (atlassianlabs/localstack) is still available but will not be maintained any longer.

Overview

LocalStack spins up the following core Cloud APIs on your local machine.

Note: Starting with version 0.11.0, all APIs are exposed via a single edge service, which is accessible on http://localhost:4566 by default (customizable via EDGE_PORT, see further below).

• ACM
• API Gateway
• CloudFormation
• CloudWatch
• CloudWatch Logs
• DynamoDB
• DynamoDB Streams
• EC2
• Elasticsearch Service
• EventBridge (CloudWatch Events)
• Firehose
• IAM
• Kinesis
• KMS
• Lambda
• Redshift
• Route53
• S3
• SecretsManager
• SES
• SNS
• SQS
• SSM
• StepFunctions
• STS

In addition to the above, the Pro version of LocalStack supports additional APIs and advanced features, including:

• Amplify
• API Gateway V2 (WebSockets support)
• AppSync
• Athena
• CloudFront
• CloudTrail
• Cognito
• ECS/ECR/EKS
• ElastiCache
• EMR
• Glacier / S3 Select
• IoT
• Kinesis Data Analytics
• Lambda Layers
• Managed Streaming for Kafka (MSK)
• MediaStore
• QLDB
• RDS / Aurora Serverless
• Timestream
• Transfer
• XRay
• Interactive UIs to manage resources
• Test report dashboards
• ...and much, much more to come!

Why LocalStack?

LocalStack builds on existing best-of-breed mocking/testing tools, notably kinesalite/dynalite and moto, ElasticMQ, and others. While these tools are awesome (!), they lack functionality for certain use cases. LocalStack combines the tools, makes them interoperable, and adds important missing functionality on top of them:

• Error injection: LocalStack allows to inject errors frequently occurring in real Cloud environments, for instance ProvisionedThroughputExceededException which is thrown by Kinesis or DynamoDB if the amount of read/write throughput is exceeded.
• Isolated processes: Services in LocalStack can be run in separate processes. In moto, components are often hard-wired in memory (e.g., when forwarding a message on an SNS topic to an SQS queue, the queue endpoint is looked up in a local hash map). In contrast, LocalStack services live in isolation (separate processes/threads communicating via HTTP), which fosters true decoupling and more closely resembles the real cloud environment.
• Pluggable services: All services in LocalStack are easily pluggable (and replaceable), due to the fact that we are using isolated processes for each service. This allows us to keep the framework up-to-date and select best-of-breed mocks for each individual service.

Requirements

• python (both Python 2.x and 3.x supported)
• pip (python package manager)
• Docker

Installing

The easiest way to install LocalStack is via pip:

pip install localstack

Note: Please do not use sudo or the root user - LocalStack should be installed and started entirely under a local non-root user. If you have problems with permissions in MacOS X Sierra, install with pip install --user localstack

Running in Docker

By default, LocalStack gets started inside a Docker container using this command:

localstack start

(Note that on MacOS you may have to run TMPDIR=/private$TMPDIR localstack start --docker if $TMPDIR contains a symbolic link that cannot be mounted by Docker.)

Note: From 2020-07-11 onwards, the default image localstack/localstack in Docker Hub refers to the "light version", which has some large dependency files like Elasticsearch removed (and lazily downloads them, if required). (Note that the localstack/localstack-light image alias may get removed in the future). In case you need the full set of dependencies, the localstack/localstack-full image can be used instead. Please also refer to the USE_LIGHT_IMAGE configuration below.

Note: By default, LocalStack uses the image tagged latest that is cached on your machine, and will not pull the latest image automatically from Docker Hub (i.e., the image needs to be pulled manually if needed).

(Note: Although it is strongly recommended to use Docker, the infrastructure can also be spun up directly on the host machine using the --host startup flag. Note that this will require additional dependencies, and is not supported on some operating systems, including Windows.)

Using docker-compose

You can also use the docker-compose.yml file from the repository and use this command (currently requires docker-compose version 1.9.0+):

docker-compose up

(Note that on MacOS you may have to run TMPDIR=/private$TMPDIR docker-compose up if $TMPDIR contains a symbolic link that cannot be mounted by Docker.)

To facilitate interoperability, configuration variables can be prefixed with LOCALSTACK_ in docker. For instance, setting LOCALSTACK_SERVICES=s3 is equivalent to SERVICES=s3.

Using Helm

You can use Helm to install LocalStack in a Kubernetes cluster by running these commands (the Helm charts are maintained in this repo):

helm repo add localstack-repo http://helm.localstack.cloud

helm upgrade --install localstack localstack-repo/localstack

Configurations

You can pass the following environment variables to LocalStack:

• EDGE_PORT: Port number for the edge service, the main entry point for all API invocations (default: 4566).
• SERVICES: Comma-separated list of service names (APIs) to start up. Service names basically correspond to the service names of the AWS CLI (kinesis, lambda, sqs, etc), although LocalStack only supports a subset of them. Example value: kinesis,lambda,sqs to start Kinesis, Lambda, and SQS. In addition, the following shorthand values can be specified to run a predefined ensemble of services:
  • serverless: run services often used for Serverless apps (iam, lambda, dynamodb, apigateway, s3, sns)
• DEFAULT_REGION: AWS region to use when talking to the API (default: us-east-1).
• HOSTNAME: Name