Separating LocalStack Community and Pro containers

In the upcoming weeks, we will merge a release candidate of LocalStack v2 into master branch, which will come into effect into the latest Docker image end of next week (March 23, 2023). From that day, it will no longer be possible to start LocalStack Pro with a LOCALSTACK_API_KEY using the localstack/localstack Docker image. Pro users should migrate to the localstack/localstack-pro image.

Depending on how you start LocalStack, here’s what you need to look out for:

  • Docker Compose: Change the image property of your service container from localstack/localstack to localstack/localstack-pro.
  • Docker command: Similar to when using Docker Compose, you simply need to specify localstack/localstack-pro as the image you want to start.
  • LocalStack CLI: Upgrade LocalStack to the latest version using pip install --upgrade localstack. The localstack CLI already uses the correct image when you have an API key set in your environment

Here’s a more detailed explanation of why we are doing this.

Separating the images

We are using the upcoming major release as an opportunity to fix a long standing issue in localstack, which is a circular dependency between the community version of LocalStack, and our proprietary LocalStack Pro extensions. To that end, we are splitting our current LocalStack (localstack/localstack) Docker Image into two seperate images:

The Community image will only contain the community version of our main product, while our latter Pro image will contain the Pro APIs and all the different tiers we offer to our paid customers. This significantly reduces the size of the community Docker image, and also makes it easier for LocalStack users to understand which version they are using. Moreover, resolving the cyclic dependency will make it easier for us to push more stable builds moving forward.

However, due to this change, LocalStack Pro users will need to explicitly pull the Pro Docker image from Docker Hub, as the community image will no longer container the code necessary to run the Pro version. Earlier, users could switch from a non-paying user to a paying customer by providing an API key using LOCALSTACK_API_KEY. With the change we are introducing, the latest Community image will no longer start if you set an API key. The Pro image will display a warning if you do not set an API key (or the key is inactive) and will not activate the Pro features.

We highly recommend that all our current Pro users update their configuration ASAP, and upgrade to the new version to avoid breaking changes once we publish the release candidate to the latest tag.

If you are running into issues with the Pro image, please get in touch with us to share your feedback and let us help you get going with the latest LocalStack version. If you have been using the Community image with an API key to activate the Pro version, please migrate your to start using the Pro image as soon as possible.

For support, don’t hesitate to contact us on our Pro support channels.