docs/development-environment-setup/README.md
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.
pip
pyenv.
This way you will always use the correct Python version as defined in .python-version.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.
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:
git clone [email protected]:<GITHUB_USERNAME>/localstack.gitpython, pip, node, and npm installed.[!NOTE] You might also need
javafor some emulated services.
make install.[!NOTE] This will install the required pip dependencies in a local Python 3
venvdirectory called.venv(your global Python packages will remain untouched). Depending on your system, somepipmodules may require additional native libs installed.
[!NOTE] Consider running
make install-dev-typesto enable type hinting for efficient integration tests development.
make start </a>
We generally recommend using this command to build the localstack/localstack Docker image locally (works on Linux/macOS):
IMAGE_NAME="localstack/localstack" ./bin/docker-helper.sh build
In host mode, additional dependencies (e.g., Java) are required for developing certain AWS-emulated services (e.g., DynamoDB). The required dependencies vary depending on the service, Configuration, operating system, and system architecture (i.e., x86 vs ARM). Refer to our official Dockerfile and our package installer LPM for more details.
LocalStack runs its own DNS server which listens for requests on port 53. This requires root permission. When LocalStack starts in host mode it runs the DNS server as sudo, so a prompt is triggered asking for the sudo password. This is annoying during local development, so to disable this functionality, use DNS_ADDRESS=0.
[!NOTE] We don't recommend disabling the DNS server in general (e.g. in Docker) because the DNS server enables seamless connectivity to LocalStack from different environments via the domain name
localhost.localstack.cloud.
g++ to fix a compile error on ARM Linux gcc: fatal error: cannot execute ‘cc1plus’
LAMBDA_DEV_PORT_EXPOSE=1 such that the host can reach Lambda containers via IPv4 in bridge mode (see #7367).git clone [email protected]:<GITHUB_USERNAME>/moto.git (using the localstack branch)# Assuming the following directory structure:
#.
#├── localstack
#└── moto
cd localstack
source .venv/bin/activate
pip install -e ../moto
virtualenv chooses system python installations before your pyenv installations, manually initialize virtualenv before running make install: virtualenv -p ~/.pyenv/shims/python3.10 .venv .tfenv to manage Terraform versions comfortable. Quick start: tfenv install 0.13.7 && tfenv use 0.13.7LS_LOG='trace' to print every http request sent to localstack and their responses. It is useful for debugging certain issues.pre-commit install. pre-commit installation: pip install pre-commit or brew install pre-commit.