Development Environment Setup
Set up your development environment for developing LocalStack.
Note
We 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.
Development requirements
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
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:
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:
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):
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.