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