LocalStack: locally test AWS with Docker

LocalStack is a test/mocking framework for developing Cloud applications that combines kinesalite/dynalite and moto, ElasticMQ, and others.

At the moment the project is focus primary on supporting the AWS cloud stack. You can run it in your local environment without even having an AWS account and start locally test AWS.

In this post, you will learn how to:

Create an AWS profile using the AWS CLI.
Run LocalStack into a Docker Container.
Access to panel UI of LocalStack.
Run some commands using AWS CLI using LocalStack.

LocalStack services

LocalStack comes in two flavors: A free, open source Base Edition, and a Pro Edition with extended features and support.

As you see the first is free and you can run it in your local machine and also second however must pay a monthly subscription and set a key into your installation to use it.

Let’s identify what services provides LocalStack in each edition.

Base Edition (Community Edition)

Pro Edition

API Gateway V2 (WebSockets support)
AppSync
Athena
CloudFront
CloudTrail
Cognito
ECS/EKS
ElastiCache
EMR
IoT
Lambda Layers
RDS
XRay
Interactive UIs to manage resources
Test report dashboards

To see more information creating an account into https://app.localstack.cloud/ (credit card is no required), on the website, for example, you will find information about how to configure it when using the Pro Edition. You can access to https://localstack-community.slack.com/ if you wish.

Prerequisites

Is possible install LocalStack using Docker or Python however the recommended way of installing is using Docker. This walkthrough assumes that LocalStack will be installed on a Windows machine :

Windows 10 Pro, Enterprise or Educational (Build 15063 or later).
Hyper-V and Containers Windows features must be enabled.

Startup

Creating an AWS profile

First we will download the AWS CLI from here.
Next, we should create a profile AWS Profile, do it into a PowerShell terminal. Set region to us-east-1 (this is important when using some services like SQS or SNS).

aws configure --profile stack-profile

After, create the profile it will be similar (path file C:\Users\yourUserName\.aws\credentials) to:

[stack-profile]
aws_access_key_id = temp
aws_secret_access_key = temp
region=us-east-1

Preparing the LocalStack container

Start setting up Docker, for it, we download and install it from here.

After install it, check the Docker installation with the following command(use Powershell).

docker --version

Once Docker is running, pull the LocalStack image. The image size is almost 500mb and uncompress is around a 1gb.

docker pull localstack/localstack:0.11.0

To avoid issues when the container starts the better option is create a folder with the following structure:

Create the docker-compose.yml, it will have the configuration for creating the container using a LocalStack image and it also has the services to starting (line 13) and the port mapping between the container and the host (line 8 and 7). Line 27 and 28 have the path for saving information to use when the container is restarted to retain its state. For a full detailed definition of the environment, parameters check the official documentation here.

version: '2.1'

services:
  localstack-container:
    container_name: "localstack-container"
    privileged: true
    image: localstack/localstack:0.11.0
    ports:
      - "4566-4599:4566-4599"
      - "8081:8081"
    # https://github.com/localstack/localstack#configurations
    environment:
      - SERVICES=s3,sqs
      - DEBUG=1
      - DATA_DIR=/tmp/localstack/data
      - PORT_WEB_UI=8081
        # LAMBDA_EXECUTOR: Method to use for executing Lambda functions. Possible values are:
        #   local: run Lambda functions in a temporary directory on the local machine
        #   docker: run each function invocation in a separate Docker container
        #   docker-reuse: create one Docker container per function and reuse it across invocations
      - LAMBDA_EXECUTOR=docker-reuse
      - KINESIS_ERROR_PROBABILITY=${KINESIS_ERROR_PROBABILITY- }
      - DOCKER_HOST=unix:///var/run/docker.sock
      - DEFAULT_REGION=us-east-1
      - START_WEB=1
    volumes:
      - "./tmp/localstack:/tmp/localstack"
      - "./tmp/localstack/run/docker.sock:/var/run/docker.sock"

Then, run the LocalStack container you must locate where is the docker-compose.yml file then execute.

docker-compose up

Stop the LocalStack container when don’t use it.

docker-compose down

Interacting with LocalStack

LocalStack Base edition provides a simple UI Web, and you can check it out at http://localhost:8081/. If everything is correct then you will see some like this.

On this page, you will see more information when starting to interact with some services, for example, S3, SQS, and so on.

After this is possible to start testing your application using LocalStack or AWS CLI to interact with some services.

Make sure to specify the endpoint and profile according to each service that you use.

Testing LocalStack and S3 Service

The most noteworthy is possible to interact with LocalStack using AWS CLI, here are some commands to use S3.

Creating a bucket

aws --profile stack-profile --endpoint-url=http://localhost:4572 s3 mb s3://yourbucket

For list the Bucket recently created

aws --profile stack-profile --endpoint-url=http://localhost:4572 s3 ls

Listing files into a bucket (you can use http://localhost:4572/yourbucket too.)

aws --profile stack-profile --endpoint-url=http://localhost:4572 s3 ls yourbucket

Conclusions

As result of these all steps you can start testing, for example, run an integration testing of a Web API that uploads and download files using S3 services or starts to send and read messages of a queue. Here you will find how to run LocalStack using DotNet instead a Docker Compose file.

Additional resources

View or download sample code for this post.