Development Environment Setup
NoteWe have recently added a couple of refactorings and enhancements in the core framework and application architecture, hence this page is no longer fully up to date. We’re planning to publish an updated version soon.
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.
You will need the following tools for the local development of LocalStack.
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
- Make sure you have
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
.venv (your global python packages will remain untouched), as well as some node modules in
./localstack/node_modules/. Depending on your system, some
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
virtualenvchooses system python installations before your pyenv installations, manually initialize
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
httprequest sent to localstack and their responses. It is useful for debugging certain issues.