Setup and requirements

    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.

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

    • Python 3.10+
    • Sasl
    • Pip
    • Virtualenv
    • OpenJDK
    • Node & npm
    • Maven
    • Gradle
    • Terraform
    • Docker
    • Docker-Compose

    Below are some basic installation instructions for the dependencies you will need (assuming you’re on Debian/Ubuntu Linux). In the case of Fedora/CentOS, most of the packages have pretty much the same name, with a few exceptions.

    • Python 3.10+

    • Pip

      1. apt-get install python3-pip
      2. update-alternatives --install /usr/bin/pip pip /usr/bin/pip3 2
      1.   pip install virtualenv

    • OpenJDK

      For Debian

      1.   apt-get install openjdk-11-jdk

      For Fedora

    • Node

      1.   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
      2.   curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
      3.   apt-get install -y nodejs

    • Maven

      1. wget https://mirrors.estointernet.in/apache/maven/maven-3/3.6.3/binaries/apache-maven-3.6.3-bin.zip -O /opt/apache-maven-3.6.3-bin.zip
      2. unzip /opt/apache-maven-3.6.3-bin.zip -d /opt/

    • Gradle

    • Terraform

      1. curl -L -o /opt/terraform/terraform.zip https://releases.hashicorp.com/terraform/0.13.4/terraform_0.13.4_linux_amd64.zip
      2. (cd /opt/terraform && unzip -q /opt/terraform/terraform.zip && rm /opt/terraform/terraform.zip)

    • Adding Environment variable

      1. echo "PATH=$PATH:/opt/apache-maven-3.6.3/bin:/opt/gradle-6.7/bin:/opt/terraform" >> ~/.bashrc && source ~/.bashrc

    • Docker-Compose

      1. sudo curl -L "https://github.com/docker/compose/releases/download/1.27.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
      2. sudo chmod +x /usr/local/bin/docker-compose
      3. sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

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

    1. 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:

    Although we strongly recommend to use Docker, the infrastructure can also be spun up directly on the host machine using the --host startup flag. Note that this will require additional dependencies, and is not supported on some operating systems, including Windows.

    1. localstack start --host

    LocalStack will attempt to automatically fetch the missing dependencies when you first start it up in host mode; Alternatively, you can use the full profile to install all dependencies at pip installation time:

    1. pip install "localstack[full]"

    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):

    • If virtualenv chooses system python installations before your pyenv installations, manually initialize virtualenv before running make install like this: 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. Useful for debugging certain issues.
    • As per dev guide, it requires libsasl2-dev. Arch based Distro equivalent: