Installation

This installation guide provides the basic instructions to install LocalStack for the first time, and assumes you are already familiar with the Docker and Python packaging ecosystems.

How to install LocalStack

The first thing when getting started with LocalStack is to choose your preferred way of starting and managing your LocalStack instance.

LocalStack currently provides the following options:

• LocalStack CLI
  The easiest way to start and manage LocalStack - either on your machine, in a Docker container on your machine, or even on a remote Docker host.

• LocalStack Cockpit
  Get a desktop experience and work with your local LocalStack instance via the UI.

• Docker
  Use the docker CLI to manually start the LocalStack Docker container.

• Docker-Compose
  Use docker-compose to configure and start your LocalStack Docker container.

• Helm
  Use helm to create a LocalStack deployment in a Kubernetes cluster.

LocalStack runs inside a Docker container, and the above options are different ways to start and manage the LocalStack Docker container. The LocalStack CLI is the easiest way to get started, and we recommend using it for your first steps with LocalStack. For a comprehensive overview of the LocalStack images, check out our Docker images documentation.

LocalStack CLI

The LocalStack CLI aims to simplify starting and managing LocalStack. It provides convenience features to start LocalStack on your local machine, as a Docker container on your machine, or even on a remote Docker host. In addition you can easily check the status or open a shell in your LocalStack instance if you want to take a deep-dive.

Prerequisites

Please make sure to install the following tools on your machine before moving ahead:

• python (Python 3.7 up to 3.10 is supported)
• pip (Python package manager)
• docker

Installation

Download the latest LocalStack release:

• macOS brew
• macOS/Linux PyPI
• Windows

brew install localstack

python3 -m pip install localstack

python -m pip install localstack

$ python3 -m pip install localstack==<version>

Afterwards you should be able to use the LocalStack CLI in your terminal:

$ localstack --help
Usage: localstack [OPTIONS] COMMAND [ARGS]...

  The LocalStack Command Line Interface (CLI)

Options:
...

Updates

The LocalStack CLI also allows you to easily update the different components of LocalStack. To check the various options available for updating, run:

$ localstack update --help

Usage: localstack update [OPTIONS] COMMAND [ARGS]...

  Update LocalStack components

Options:
  --help  Show this message and exit.

Commands:
  all             Update all LocalStack components
  docker-images   Update container images LocalStack depends on
  localstack-cli  Update LocalStack CLI tools

You can decide to update the CLI itself, the LocalStack Docker images, or all at once:

$ # Update all components
$ localstack update all
$ # Only update the LocalStack docker images
$ localstack update docker-images
$ # Only update the LocalStack CLI
$ localstack update localstack-cli

Starting LocalStack with the LocalStack CLI

By default, LocalStack is started inside a Docker container by running:

$ localstack start

LocalStack Cockpit

See LocalStack Cockpit.

Docker

To use LocalStack without the LocalStack CLI, you have the option of running the LocalStack Docker container by yourself. This method requires more manual steps and configuration, but it gives you more control over the container settings and environment variables.

Prerequisites

Please make sure that you have a working docker environment on your machine before moving on. You can check if docker is correctly configured on your machine by executing docker info in your terminal. If it does not report an error (but shows information on your Docker system), you’re good to go.

Starting LocalStack with Docker

You can start the Docker container simply by executing the following docker run command:

• Community
• Pro

docker run \
  --rm -it \
  -p 4566:4566 \
  -p 4510-4559:4510-4559 \
  localstack/localstack

docker run \
  --rm -it \
  -p 4566:4566 \
  -p 4510-4559:4510-4559 \
  -e LOCALSTACK_API_KEY=${LOCALSTACK_API_KEY:- } \
  localstack/localstack-pro

Docker-Compose

If you want to manually manage your Docker container, it’s usually a good idea to use docker-compose in order to simplify your container configuration.

Prerequisites

• docker
• docker-compose (version 1.9.0+)

Starting LocalStack with Docker-Compose

You can start LocalStack with Docker Compose by configuring a docker-compose.yml file. Currently, docker-compose version 1.9.0+ is supported.

• Community
• Pro

version: "3.8"

services:
  localstack:
    container_name: "${LOCALSTACK_DOCKER_NAME-localstack_main}"
    image: localstack/localstack
    ports:
      - "127.0.0.1:4566:4566"            # LocalStack Gateway
      - "127.0.0.1:4510-4559:4510-4559"  # external services port range
    environment:
      - DEBUG=${DEBUG-}
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

version: "3.8"

services:
  localstack:
    container_name: "${LOCALSTACK_DOCKER_NAME-localstack_main}"
    image: localstack/localstack-pro  # required for Pro
    ports:
      - "127.0.0.1:4566:4566"            # LocalStack Gateway
      - "127.0.0.1:4510-4559:4510-4559"  # external services port range
      - "127.0.0.1:53:53"                # DNS config (required for Pro)
      - "127.0.0.1:53:53/udp"            # DNS config (required for Pro)
      - "127.0.0.1:443:443"              # LocalStack HTTPS Gateway (required for Pro)
    environment:
      - DEBUG=${DEBUG-}
      - PERSISTENCE=${PERSISTENCE-}
      - LOCALSTACK_API_KEY=${LOCALSTACK_API_KEY-}  # required for Pro
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

Start the container by running the following command:

$ docker-compose up

Please note that there are a few pitfalls when configuring your stack manually via docker-compose (e.g., required container name, Docker network, volume mounts, and environment variables). We recommend using the LocalStack CLI to validate your configuration, which will print warning messages in case it detects any potential misconfigurations:

$ localstack config validate
...

Helm

If you want to deploy LocalStack in your Kubernetes cluster, you can use Helm.

Prerequisites

• Kubernetes
• Helm

Deploy LocalStack using Helm

You can deploy LocalStack in a Kubernetes cluster by running these commands:

$ helm repo add localstack-repo https://helm.localstack.cloud
$ helm upgrade --install localstack localstack-repo/localstack

The Helm charts are not maintained in the main repository, but in a separate one.

Troubleshooting

• The LocalStack CLI installation is successful, but I cannot execute localstack on my terminal.

  If you can successfully install LocalStack using pip but you cannot use it in your terminal, you most likely haven’t set up your operating system’s / terminal’s PATH variable (in order to tell them where to find programs installed via pip).

  • If you are using Windows, you can enable the PATH configuration when installing Python, as described in the official docs of Python.
  • If you are using a MacOS or Linux operating system, please make sure that the PATH is correctly set up - either system wide, or in your terminal.

  As a workaround you can call the LocalStack CLI python module directly:

  $ python3 -m localstack.cli.main

• How should I access the LocalStack logs on my local machine?

  You can now avail logging output and error reporting using LocalStack logs. To access the logs, run the following command:

  $ localstack logs

  AWS requests are now logged uniformly in the INFO log level (set by default or when DEBUG=0). The shape is AWS <service>.<operation> => <http-status> (<error type>). Requests to HTTP endpoints are logged in a similar way:

  2022-09-12T10:39:21.165  INFO --- [   asgi_gw_0] localstack.request.aws     : AWS s3.ListBuckets => 200
  2022-09-12T10:39:41.315  INFO --- [   asgi_gw_0] localstack.request.aws     : AWS s3.CreateBucket => 200
  2022-09-12T10:40:04.662  INFO --- [   asgi_gw_0] localstack.request.aws     : AWS s3.PutObject => 200
  2022-09-12T11:01:55.799  INFO --- [   asgi_gw_0] localstack.request.http    : GET / => 200
  

• How should I share the LocalStack logs to discover issues?

  You can now share the LocalStack logs with us to help us discover issues. To share the logs, run our diagnostic endpoint:

  $ curl -s localhost:4566/_localstack/diagnose | gzip -cf > diagnose.json.gz

  Ensure that the diagnostic endpoint is run after you have tried reproducing the affected task. After running the task, run the diagnostic endpoint and share the archive file with your team members or LocalStack Support.

What’s next?

Now that you have LocalStack up and running, the following resources might be useful for your next steps:

• Check out our Quickstart guide if you are a new user to get started with LocalStack quickly.
• Use the LocalStack integrations to interact with LocalStack and other integrated tools, for example:
  • Use awslocal to use the AWS CLI against your local cloud!
  • Use the Serverless Framework with LocalStack!
  • And many more!
• Find out how to configure LocalStack such that it perfectly fits your need.
• Use LocalStack in your CI environment to increase your code quality.
• Checkout LocalStack’s Cloud Developer Tools to further increase your development efficiency with LocalStack.
• Find out about the ways you can configure LocalStack.