Migrating to LocalStack v1.0

Announcement
, ,
1

We have released LocalStack v1.0 with significant changes for our community users and pro customers. We aim to confidently drive individual productivity and team collaboration by providing a comprehensive ecosystem of local AWS services, integrations and tools to make cloud development a breeze.

With LocalStack v1.0, users would need to migrate their existing LocalStack configurations and take note of some deprecated features. Let’s take a look at how you can migrate to LocalStack v1.0 easily in a few steps.

Update your startup configurations to the new LocalStack volume directory

Starting with docker-compose

Update your volumes mounts from:

     volumes:
      - "${TMPDIR:-/tmp}/localstack:/tmp/localstack"

to:

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

Starting with docker

Update your volume mounts from:

docker run -p 4566:4566 -v /tmp/localstack:/tmp/localstack ...

to

docker run -p 4566:4566 -v /path/to/volume:/var/lib/localstack ...

where /path/to/volume should be something outside your host’s temp folder. We encourage the cache directory of your system.

Starting with the command-line interface

Just update to the latest version of the CLI with pip install --upgrade localstack. The latest version of the CLI already uses the new LocalStack volume directory.

The volume directory can be configured via the LOCALSTACK_VOLUME_DIR, which defaults to:

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

Miscellaneous

  • The old filesystem hierarchy (including /tmp/localstack mounts,DATA_DIRand HOST_TMP_PATH) can be enabled using LEGACY_DIRECTORIES=1.

  • If you mount a volume into /tmp/localstack instead of /var/lib/localstack, then LocalStack will automatically enable LEGACY_DIRECTORIES=1, and print a deprecation warning.

  • You currently cannot set the configure the new filesystem hierarchy with the CLI version 0.14.x, in order to use the development version of the CLI. Please run pip install --upgrade "localstack>=1.0.0.dev".

  • Remove DATA_DIR which has been deprecated and will be ignored. Use PERSISTENCE=1 and find your state files in your LocalStack volume in state/.

  • Remove HOST_TMP_PATH, which was previously necessary for LAMBDA_EXECUTOR=docker or docker-reuse. We now detect automatically the host path that is mounted into Lambda containers from your LocalStack volume mount.

  • When using docker-compose, remove the network_mode: bridge configuration unless you are sure that you need it. We now automatically detect the network mode for Lambda networking.

  • We’ve rolled out a completely new framework for handling AWS requests, the AWS Server Framework (ASF). This has replaced the edge proxy, which was previously handling all HTTP requests. If you are experiencing problems, as a workaround you can try to enable the old edge proxy with LEGACY_EDGE_PROXY=1. However this is deprecated and will be removed in the future.

  • Enable the experimental multi-accounts feature by setting MULTI_ACCOUNTS=1 as part of your LocalStack config. New AWS accounts will be allocated based on configuration from the client side. See our documentation for details.

  • Replay-based persistence has been removed. To use our more mature persistence mechanism, please consider upgrading to LocalStack Pro.

4 Likes