Filesystem Layout

Overview of runtime directory structure

This page describes the filesystem directory layout used internally by LocalStack.

Filesystem layout

Information

This filesystem layout was introduced in LocalStack v1 and can be disabled by setting LEGACY_DIRECTORIES to 1.

LocalStack uses following directories when running within a container.

  • /var/lib/localstack: the LocalStack volume directory root
  • /var/lib/localstack/lib: variable packages (like extensions or lazy-loaded third-party dependencies)
  • /var/lib/localstack/logs: logs for recent LocalStack runs
  • /var/lib/localstack/state: contains the state of services if persistence is enabled (such as OpenSearch cluster data)
  • /var/lib/localstack/tmp: temporary data that is not expected to survive LocalStack runs (may be cleared when LocalStack starts or stops)
  • /var/lib/localstack/cache: temporary data that is expected to survive LocalStack runs (is not cleared when LocalStack starts or stops)
  • /usr/lib/localstack: static third-party packages installed into the container images

Warning

Previously, directories were individually configurable, e.g., via DATA_DIR or HOST_TMP_DIR. These have been deprecated since LocalStack v1, since we now follow a directory convention.

DATA_DIR implicitly points to /var/lib/localstack/state if persistence is enabled. Use PERSISTENCE=1 to enable persistence. If DATA_DIR is set, its value is ignored, a warning is logged and PERSISTENCE is set to 1.

HOST_TMP_FOLDER is determined by inspecting the volume mounts and using the source of the bind mount to /var/lib/localstack.

LocalStack volume

For LocalStack to function correctly, the LocalStack volume must be mounted from the host into the container at /var/lib/localstack.

Using docker-compose

When using Docker Compose, this can be achieved using following:

  1. volumes:
  2.   - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"

${LOCALSTACK_VOLUME_DIR} could be an arbitrary location on the host, e.g., ./volume. In this case, the effective layout would be something like:

  1. $ tree -L 4 ./volume
  2. .
  3. └── localstack
  4.     ├── cache
  5.     │   ├── machine.json
  6.     │   ├── server.test.pem
  7.     │   ├── server.test.pem.crt
  8.     │   └── server.test.pem.key
  9.     ├── lib
  10.     │   └── opensearch
  11.     │       └── 1.1.0
  12.     ├── logs
  13.     │   ├── localstack_infra.err
  14.     │   └── localstack_infra.log
  15.     ├── state
  16.     │   └── startup_info.json
  17.     └── tmp
  18.         └── zipfile.4986fb95

Using the CLI

When using the CLI to start LocalStack, the volume directory can be configured via the LOCALSTACK_VOLUME_DIR. It should point to a directory on the host which is then automatically mounted into /var/lib/localstack. The defaults are:

  • Mac: ~/Library/Caches/localstack/volume
  • Linux: ~/.cache/localstack/volume
  • Windows: %LOCALAPPDATA%/localstack/cache/volume

Host mode

When LocalStack is running in host mode, the system directories /usr/lib/localstack or /var/lib/localstack are not used. Instead, the root directory is changed to FILESYSTEM_ROOT which defaults to ./.filesystem, i.e. the LocalStack project root.

Last modified July 13, 2022: update filesystem description and configuration (#201) (ee1c122c)