LocalStack: locally test AWS with Docker

  • AWS
AWS - Docker - LocalStack

LocalStack is a test/mocking framework for developing Cloud applications that combines kinesalite/dynalite and motoElasticMQ, 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 at http://localhost:4567
Kinesis at http://localhost:4568
DynamoDB at http://localhost:4569
DynamoDB Streams at http://localhost:4570
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
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
SSM at http://localhost:4583
SecretsManager at http://localhost:4584
StepFunctions at http://localhost:4585
CloudWatch Logs at http://localhost:4586
EventBridge (CloudWatch Events) at http://localhost:4587
STS at http://localhost:4592
IAM at http://localhost:4593
EC2 at http://localhost:4597
KMS at http://localhost:4599
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

  1. First we will download the AWS CLI from here.
  2. 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
  1. 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

  1. Start setting up Docker, for it, we download and install it from here.
  1. After install it, check the Docker installation with the following command(use Powershell).
docker --version
  1. 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
  1. To avoid issues when the container starts the better option is create a folder with the following structure:
Tree view
  1. 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"
  1. Then, run the LocalStack container you must locate where is the docker-compose.yml file then execute.
docker-compose up
  1. 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.


Leave a Reply

Your email address will not be published. Required fields are marked *