Filesystem Layout
This page describes the filesystem directory layout used internally by LocalStack.
LocalStack uses following directory layout when running within a container.
Directoryetc
Directorylocalstack
- init
Directoryusr
Directorylib
- localstack
Directoryvar
Directorylib
Directorylocalstack the LocalStack volume directory root
- cache
- lib
- logs
- state
- tmp
Directory contents
Section titled “Directory contents”LocalStack volume directory
Section titled “LocalStack volume directory”/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)
Configuration
Section titled “Configuration”/etc/localstack
: configuration directory/etc/localstack/init
: root directory for initialization hooks
Static libraries
Section titled “Static libraries”/usr/lib/localstack
: static third-party packages installed into the container images
LocalStack volume
Section titled “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
Section titled “Using docker-compose”When using Docker Compose, this can be achieved using following:
volumes: - "${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:
Directorylocalstack
Directorycache
- machine.json
- server.test.pem
- server.test.pem.crt
- server.test.pem.key
Directorylib
Directoryopensearch
- 1.1.0
Directorylogs
- localstack_infra.err
- localstack_infra.log
Directorystate
- startup_info.json
Directorytmp
- zipfile.4986fb95
Using the CLI
Section titled “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%\cache\localstack\volume
Host mode
Section titled “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.