Please Note: Repository Inactive

This repository is no longer actively maintained. LocalStack has been forked and is now maintained in a new location:

https://github.com/localstack/localstack

Please do not create pull requests against this repository. Thanks

Below is a copy of the original README.

LocalStack - A fully functional local AWS cloud stack

LocalStack

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

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

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

API Gateway at http://localhost:4567
Kinesis at http://localhost:4568
DynamoDB at http://localhost:4569
DynamoDB Streams at http://localhost:4570
Elasticsearch at http://localhost:4571
S3 at http://localhost:4572
Firehose at http://localhost:4573
Lambda at http://localhost:4574
SNS at http://localhost:4575
SQS at http://localhost:4576
Redshift at http://localhost:4577
ES (Elasticsearch Service) at http://localhost:4578
SES at http://localhost:4579
Route53 at http://localhost:4580
CloudFormation at http://localhost:4581
CloudWatch at http://localhost:4582

Additionally, LocalStack provides a powerful set of tools to interact with the cloud services, including a fully featured KCL Kinesis client with Python binding, simple setup/teardown integration for nosetests, as well as an Environment abstraction that allows to easily switch between local and remote Cloud execution.

Why LocalStack?

LocalStack builds on existing best-of-breed mocking/testing tools, most notably kinesalite/dynalite and moto. 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.
Actual HTTP REST services: All services in LocalStack allow actual HTTP connections on a TCP port. In contrast, moto uses boto client proxies that are injected into all methods annotated with @mock_sqs. These client proxies do not perform an actual REST call, but rather call a local mock service method that lives in the same process as the test code.
Language agnostic: Although LocalStack is written in Python, it works well with arbitrary programming languages and environments, due to the fact that we are using the actual REST APIs via HTTP.
Isolated processes: All services in LocalStack run in separate processes. The overhead of additional processes is negligible, and the entire stack can easily be executed on any developer machine and CI server. In moto, components are often hard-wired in RAM (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 available 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 (e.g., kinesalite is much more advanced than its moto counterpart).

Requirements

make
python (both Python 2.x and 3.x supported)
pip (python package manager)
npm (node.js package manager)
java/javac (Java 8 runtime environment and compiler)
mvn (Maven, the build system for Java)

Installing

The easiest way to install LocalStack is via pip:

pip install localstack

Once installed, run the infrastructure using the following command:

localstack start

Note: Please do not use sudo or the root user - LocalStack should be installed and started entirely under a local non-root user.

Running in Docker

You can also spin up LocalStack in Docker:

localstack start --docker

Or using docker-compose (you need to clone the repository first):

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

Configurations

You can pass the following environment variables to LocalStack:

SERVICES: Comma-separated list of service names and (optional) ports they should run on. If no port is specified, a default port is used. 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:4569,sqs:4570 to start Kinesis on the default port, Lambda on port 4569, and SQS on port 4570.
DEFAULT_REGION: AWS region to use when talking to the API (defaults to us-east-1).
HOSTNAME: If you need to expose your services on a specific host (defaults to localhost).
USE_SSL: Whether to use https://... URLs with SSL encryption (defaults to false).
KINESIS_ERROR_PROBABILITY: Decimal value between 0.0 (default) and 1.0 to randomly inject ProvisionedThroughputExceededException errors into Kinesis API responses.
DYNAMODB_ERROR_PROBABILITY: Decimal value between 0.0 (default) and 1.0 to randomly inject ProvisionedThroughputExceededException errors into DynamoDB API responses.
LAMBDA_EXECUTOR: Method to use for executing Lambda functions. Valid values are local (run the code in a temporary directory on the local machine) or docker (run code in a separate Docker container). In the latter case, if LocalStack itself is started inside Docker, then the docker command needs to be available inside the container (usually requires to run the container in privileged mode). Default is docker, fallback to local if Docker is not available.
LAMBDA_REMOTE_DOCKER:
- when set to false (default): your lambda functions definitions will be passed to the container by mounting the volume (potentially faster) It is mandatory to have the Docker client and the Docker host on the same machine
- when set to true: your lambda functions definitions will be passed to the container by copying the zip file (potentially slower). It allows for remote execution, where the host and the client are not on the same machine
DATA_DIR: Local directory for saving persistent data (currently only supported for these services: Kinesis, DynamoDB, Elasticsearch). Set it to /tmp/localstack/data to enable persistence (/tmp/localstack is mounted into the Docker container), leave blank to disable persistence (default).

Accessing the infrastructure via CLI or code

You can point your aws CLI to use the local infrastructure, for example:

aws --endpoint-url=http://localhost:4568 kinesis list-streams
{
    "StreamNames": []
}

NEW: Check out awslocal, a thin CLI wrapper that runs commands directly against LocalStack (no need to specify --endpoint-url anymore). Install it via pip install awscli-local, and then use it as follows:

awslocal kinesis list-streams
{
    "StreamNames": []
}

Client Libraries

Python: https://github.com/localstack/localstack-python-client
- alternatively, you can also use boto3 and use the endpoint_url parameter when creating a connection
(more coming soon...)

Integration with nosetests

If you want to use LocalStack in your integration tests (e.g., nosetests), simply fire up the infrastructure in your test setup method and then clean up everything in your teardown method:

from localstack.mock import infra

def setup():
    infra.start_infra(async=True)

def teardown():
    infra.stop_infra()

def my_app_test():
    # here goes your test logic

See the example test file tests/test_integration.py for more details.

Integration with Java/JUnit

In order to use LocalStack with Java, the project ships with a simple JUnit runner. Take a look at the example JUnit test in ext/java. When you run the test, all dependencies are automatically downloaded and installed to a temporary directory in your system.

@RunWith(LocalstackTestRunner.class)
public class MyCloudAppTest {

  @Test
  public void testLocalS3API() {
    AmazonS3 s3 = new AmazonS3Client(...);
    s3.setEndpoint(LocalstackTestRunner.getEndpointS3());
    List<Bucket> buckets = s3.listBuckets();
    ...
  }

}

The LocalStack JUnit test runner is published as a Maven artifact in the Bitbucket repository. Simply add the following configuration to your pom.xml file:

<project ...>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>com.atlassian</groupId>
      <artifactId>localsta

Localstack

Install / Use

README