DEV Community


SAM Local with Localstack

vikasgarghb profile image Vikas Garg ・2 min read

As a developer, I look for making local dev experience as smooth as possible. In the same vein, one thing that bothers most of us working with aws cloud is to test it locally. Good thing is that we have localstack to our rescue. This post will focus on how you can have AWS SAM working with Localstack.

Table Of Contents


Project Setup

For this post, we will use sam init to pull in the hello-world project with nodejs runtime. More information on SAM. After following the prompts, you will get a sample hello world project setup running in node.

Setting up Localstack

In order to setup localstack in the project, we will first create a docker-compose.yml in the root of our project.

version: "3"
    build: localstack
    container_name: localstack
      - DATA_DIR=/tmp/localstack/data
      - SERVICES=s3 # this can be a comma separated list of services you want to start
      - TZ=America/New_York
      - '4572:4572' # these ports will be different for different services.

Another thing that we will need to do is create a directory called localstack with following contents,


Let's see what each of these files will look like, .dockerignore



FROM localstack/localstack

COPY /. /tmp/localstack/data

We will get to the contents of the json file later. Once we have this, we are ready to start the localstack in a docker container. You can do this by running,
docker-compose up -d. This will pull the localstack image and build it and start it.

S3 bucket

Now we will need to create a s3 bucket in our localstack container. For this we can just run this: awslocal s3 mb s3://test-bucket. This will create the bucket. Now bash into the container, docker exec -it localstack /bin/bash and then go to vi /tmp/localstack/data/recorded_api_calls.json. Copy the contents of this file and paste them in the file recorded_api_calls.json in the localstack directory we created earlier. We need to do this, so that we don't need to create the bucket every time we start the container.

Hooking it up

Now if you want to setup your project to use any AWS components like S3, IAM, STS etc. you can do so and test them without going to AWS directly.

In the code, you will need aws-sdk to initialize the s3 client, you can do this by,

const s3 = AWS.S3({ endpoint: 'http://localhost:4572' });

Coming back to make sam local invoke work with localstack. For this, bare minimum you would need to do this:

sam local invoke --docker-network host

For more information on sam local

Full working code can be found here:


This project contains source code and supporting files for a serverless application that you can deploy with the SAM CLI. It includes the following files and folders.

  • hello-world - Code for the application's Lambda function.
  • events - Invocation events that you can use to invoke the function.
  • hello-world/tests - Unit tests for the application code.
  • template.yaml - A template that defines the application's AWS resources.

The application uses several AWS resources, including Lambda functions and an API Gateway API. These resources are defined in the template.yaml file in this project. You can update the template to add AWS resources through the same deployment process that updates your application code.

If you prefer to use an integrated development environment (IDE) to build and test your application, you can use the AWS Toolkit.
The AWS Toolkit is an open source plug-in for popular IDEs that uses the SAM CLI to build…


Editor guide