Development Environment Setup

Before you get started with contributing to LocalStack, make sure you’ve familiarized yourself with LocalStack from the perspective of a user. You can follow our getting started guide. Once LocalStack runs in your Docker environment and you’ve played around with the LocalStack and awslocal CLI, you can move forward to set up your developer environment.

Development requirements

You will need the following tools for the local development of LocalStack.

• Python 3.11+
• pip
• virtualenv
• OpenJDK
• NodeJS & npm
• Maven
• Gradle
• Terraform
• Docker
• Docker-Compose

We recommend you to individually install the above tools using your favorite package manager. For example, on macOS, you can use Homebrew to install the above tools.

Setting up Development Environment

To make contributions to LocalStack, you need to be able to run LocalStack in host mode from your IDE, and be able to attach a debugger to the running LocalStack instance. We have a basic tutorial to cover how you can do that.

The basic steps include:

• Clone the localstack repository, and optionally our fork of moto:
  • https://github.com/localstack/localstack/
  • https://github.com/localstack/moto
• Make sure you have javac, node, npm, and Python 3.10 installed.
• Most of the contributors use the free community version PyCharm.

If you pull the repo in order to extend/modify LocalStack, run this command to install all the dependencies:

$ make install

This will install the required pip dependencies in a local Python virtualenv directory .venv (your global python packages will remain untouched), as well as some node modules in ./localstack/node_modules/. Depending on your system, some pip/npm modules may require additional native libs installed.

The Makefile contains a start command to conveniently start:

$ make start

Building the Docker image for Development

Please note that there are a few commands we need to run on the host to prepare the local environment for the Docker build - specifically, downloading some dependencies like the StepFunctions local binary. Therefore, simply running docker build . in a fresh clone of the repo may not work.

We generally recommend using this command to build the Docker image locally (works on Linux/MacOS):

$ make docker-build

Tips

• If virtualenv chooses system python installations before your pyenv installations, manually initialize virtualenv before running make install: virtualenv -p ~/.pyenv/shims/python3.10 .venv .
• Terraform needs version <0.14 to work currently. Use tfenv (https://github.com/tfutils/tfenv) to manage terraform versions comfortable. Quick start: tfenv install 0.13.7 && tfenv use 0.13.7
• Set env variable LS_LOG='trace' to print every http request sent to localstack and their responses. It is useful for debugging certain issues.