How to Set up LocalStack for Local AWS Cloud Development

LocalStack is a cloud service emulator that runs locally in your system utilizing Docker. It allows you to develop and test AWS applications or Lambdas along with CI/CD and IaC tools such as CircleCI, GitHub Actions and Terraform.

LocalStack emulates a growing number of AWS services such as Lambda, S3 (Simple Storage Service), DynamoDB, Kinesis, SQS (Simple Queue Service), SNS (Simple Notification Service), and more. LocalStack Pro – its premium offering that starts at $35 per user per month – supports more services like Amplify, Athena, Backup, CloudFront, Cognito Identity, EKS (Elastic Kubernetes Service), ELB (Elastic Load Balancing), EMR (Elastic Map Reduce), Glue, Lake Formation, Redshift, etc.

LocalStack supports various integrations | Image credit: LocalStack

It can be set up as a local cloud sandbox for development and testing of cloud apps in your local system as well as a CI/CD environment to support automated testing. Along with the ease of developing and testing your code in a local environment, you also get the benefit of additional cost savings related to developing or testing on AWS Cloud.

In this post, I’m going to show you how to install and set up LocalStack to develop and test cloud applications locally.

Install LocalStack + Tools

Install LocalStack

LocalStack is a Python package that depends on Docker for containerization. You can easily install it in your system or an Anaconda or Python environment per your preference. That said, LocalStack has a few prerequisites as well:

After you have got these prerequisites, run the following commands in or out of an Anaconda or Python environment:

1## Install the latest version of LocalStack on your system
2# Replace `python3` with `python` if it doesn't work
3python3 -m pip install localstack
4
5## Test the installed version of LocalStack on your system
6# This also confirms that it got installed successfully
7localstack --version

Install AWSLocal

AWSLocal is a command-line tool that directs all command-line calls through LocalStack instead of AWS. For example, the command aws dynamodb list-tables lists all tables in the “default” database in DynamoDB of your AWS Account, but the command awslocal dynamodb list-tables lists all tables in DynamoDB hosted on your system by LocalStack.

AWSLocal works by proxying the AWS CLI (the official command-line client of AWS) and adding --endpoint-url http://localhost:4566/ (the endpoint for LocalStack running on your system) for each call or command, making it easy for you to work with LocalStack. You only need to replace aws with awslocal in your commands. Here’s how to install it:

1## Install the latest version of AWSLocal on your system
2# Replace `python3` with `python` if it doesn't work
3python3 -m pip install awscli-local

Install LocalStack Cockpit (optional)

LocalStack Cockpit is a cross-platform desktop tool for LocalStack; similar to how Docker Desktop works for Docker. It allows you to start, stop and check the status of LocalStack on your system. It performs initialization checks to ensure the LocalStack is set up correctly. Moreover, you can check environment information, available services along with their statuses and logs as well as manage profiles (aka run configurations) that include environment variables.

However, LocalStack Cockpit has its caveats as well – at least at the moment. It’s still at version 0.2 in January 2023, and so, it is missing some essential features for now. First and most important, you can check the list and statuses of its services, but you cannot start and stop them from LocalStack Cockpit yet. You must use LocalStack CLI for those.

Nevertheless, it comes handy. Click here to download and install LocalStack Cockpit for Linux, macOS or Windows.

LocalStack Cockpit is an integrated desktop tool

Develop with LocalStack

LocalStack helps you easily develop using the awslocal command-line tool. After you have started LocalStack using the command given below, you can run awslocal commands on your local cloud infrastructure. For example, you can run awslocal s3api create-bucket --bucket example to create a S3 bucket named “example” in LocalStack. Its team has created a sample application that you can check to understand building and creating with LocalStack (check here ).

1# Start LocalStack for offline development
2localstack start
3
4# Stop LocalStack and clean up the resources
5localstack stop

After you have started LocalStack and tried out a few awslocal commands, let’s try out a common use case. Let’s create two S3 buckets through LocalStack: one using AWS CLI (or AWSLocal in this case) and the other using a Cloud Formation script. Then, we can test both S3 buckets by reading and writing files from/to the newly-created bucket. Also, we’ll need one S3 bucket to store the Cloud Formation script too. It’s a small example of what you can do with LocalStack.

Prerequisite: Create a CF Script

Create a new YAML file in your favorite text editor and save it as test-bucket.yaml having the following content:

 1AWSTemplateFormatVersion: "2010-09-09"
 2Description: Cloud Formation script to Create a S3 Bucket
 3
 4Resources:  
 5  TestBucket:
 6    Type: "AWS::S3::Bucket"
 7    Properties:
 8      BucketName: test
 9      BucketEncryption:
10        ServerSideEncryptionConfiguration:
11          - ServerSideEncryptionByDefault:
12              SSEAlgorithm: AES256
13
14Outputs:
15  TestBucketName:
16    Description: Name of the test bucket
17    Value: !Ref TestBucket

Configure AWS CLI for LocalStack

Firstly, you must run aws configure to set credentials and default region and output formal for AWS CLI (which is required for AWSLocal as well). Since we are working with AWSLocal and LocalStack here, we will set test for credentials.

1## Configure AWS CLI as the following:
2# AWS Access Key ID [None]: test
3# AWS Secret Access Key [None]: test
4# Default region name [None]: us-east-1
5# Default output format [None]: json

Create a S3 Bucket via AWS CLI

After you have configured AWS CLI, run the following commands to create a S3 bucket in LocalStack using AWSLocal. Thereafter, you can test these: the bucket exists and files can be transferred to/from the newly-created bucket.

 1###
 2# CREATE S3 BUCKET
 3###
 4
 5# Create a S3 bucket named `example`
 6awslocal s3api create-bucket --bucket example
 7
 8# List all S3 buckets in LocalStack
 9awslocal s3api list-buckets
10
11## OUTPUT (you must see `example` below):
12#{
13#  "Buckets": [
14#    {
15#      "Name": "example",
16#      "CreationDate": "2023-02-02T10:33:23.000Z"
17#    }
18#  ],
19#  "Owner": {
20#    "DisplayName": "webfile",
21#    "ID": "bcaf1ffd86f41161ca5fb16fd081034f"
22#  }
23#}
24
25
26###
27# TEST S3 BUCKET
28###
29
30# Upload any file to the bucket
31awslocal s3 cp .\test-bucket.yaml s3://example/
32
33# List the newly-created S3 bucket
34awslocal s3 ls s3://example/
35
36## OUTPUT (you must see `test-bucket.yaml` below):
37# 2023-02-01 21:10:49        446 test-bucket.yaml
38
39
40###
41# DELETE S3 BUCKET
42###
43
44# Delete files, then delete the S3 bucket itself
45awslocal s3 rm s3://example/ --recursive
46awslocal s3api delete-bucket --bucket example

Create a S3 Bucket via Cloud Formation

Finally, you need to run the given commands to run the Cloud Formation script we created above to create a S3 bucket using Cloud Formation. Then, we will test the S3 bucket by transferring files to/from the bucket, then delete the bucket.

 1###
 2# CREATE S3 BUCKET
 3###
 4
 5# Create a S3 bucket named `example` via Cloud Formation
 6awslocal cloudformation deploy --stack-name example --template-file ".\test-bucket.yaml"
 7
 8# List all S3 buckets in LocalStack
 9awslocal s3api list-buckets
10
11## OUTPUT (you must see `example` below):
12#{
13#  "Buckets": [
14#    {
15#      "Name": "example",
16#      "CreationDate": "2023-02-02T10:33:23.000Z"
17#    }
18#  ],
19#  "Owner": {
20#    "DisplayName": "webfile",
21#    "ID": "bcaf1ffd86f41161ca5fb16fd081034f"
22#  }
23#}
24
25
26###
27# TEST S3 BUCKET
28###
29
30# Upload any file to the bucket
31awslocal s3 cp .\test-bucket.yaml s3://example/
32
33# List the newly-created S3 bucket
34awslocal s3 ls s3://example/
35
36## OUTPUT (you must see `test-bucket.yaml` below):
37# 2023-02-01 21:10:49        446 test-bucket.yaml
38
39
40###
41# DELETE S3 BUCKET
42###
43
44# Delete files, then delete the S3 bucket itself
45# by deleting the Cloud Formation stack created above
46awslocal s3 rm s3://example/ --recursive
47awslocal cloudformation delete-stack --stack-name example

Hope you find the tutorial helpful in setting up LocalStack along with AWSLocal and LocalStack Cockpit. Also, how to use LocalStack for an offline cloud development experience for AWS Cloud. Though this post shows a small example of an use case of LocalStack, it proves LocalStack can be utilized for developing and testing cloud applications locally. Try it out.

References

Getting Started - Installation [ LocalStack Docs (original) (archived) ]
Getting Started - Troubleshooting [ LocalStack Docs (original) (archived) ]
Getting Started - Quickstart [ LocalStack Docs (original) (archived) ]
AWS Service Feature Coverage [ LocalStack Docs (original) (archived) ]
LocalStack Integrations [ LocalStack Docs (original) (archived) ]
Setup the sample AWS application [ LocalStack Docs (original) (archived) ]