Skip to content

docs: updating docker tags and defining them #664

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
quetzalliwrites wants to merge 1 commit into
base: main
Choose a base branch
from
+50 −37
Open

docs: updating docker tags and defining them #664

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions src/content/docs/aws/capabilities/config/docker-images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,20 @@ While configuring to run LocalStack with Docker or Docker Compose, run the `loca

## Image tags

Starting with the end-of-March 2026 release, LocalStack version tags follow
[calendar versioning](https://calver.org/) in the `YYYY.MM.patch` format (for example, `2026.03.0`).
Starting with the end-of-March 2026 release, LocalStack version tags follow [calendar versioning](https://calver.org/) in the `YYYY.MM.patch` format (for example, `2026.03.0`). Releases up to and including `v4.14.0` use [semantic versioning](https://semver.org).

Releases up to and including `v4.14.0` use [semantic versioning](https://semver.org).
To ensure that we move quickly and steadily, we run nightly builds, where all our updates are available on the `latest` tag of LocalStack's Docker image.
We intend to announce more significant features and enhancements during major & minor releases.
We occasionally create patch releases for minor bug fixes and enhancements, to ensure that we can deliver changes quickly while not breaking your existing workflows (in case you prefer not to use `latest`).
The following tags are available for the LocalStack Docker image:

Visit the [LocalStack for AWS tag](https://hub.docker.com/r/localstack/localstack-pro/tags?page=1&ordering=last_updated) in Docker Hub pages.
| Tag | Updated when | Recommended for |
|---|---|---|
| `latest` / `stable` | Tagged releases only (e.g. `2026.05.0`) | Most users — stable, release-quality builds |
| `dev` | Every merged commit on `main` | Users who need the latest unreleased changes |
| `nightly` | Scheduled nightly builds | CI pipelines that need a fresh build on a regular cadence |
Copy link
Copy Markdown
Collaborator

@remotesynth remotesynth May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we reconfirm that this image should exist? We've said that it should but I am not seeing a nightly on either AWS or Snowflake, only on Azure.

Copy link
Copy Markdown

@aidehn aidehn May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These should exist for AWS and Azure - Snowflake doesn't support this but can support this with a small change, it's just not something that has been set up yet. I can update this tomorrow so there's consistency if that's something we want for consistency!

In terms of why AWS hasn't got the nightly tag yet, it's because the PR to add these was added yesterday, but todays scheduled run didn't complete successfully (see here). Once there is a successful run it will exist 👍🏼

| `YYYY.MM` (e.g. `2026.05`) | Each patch release within that month | Users who want bugfixes but want to avoid feature changes |
| `YYYY.MM.patch` (e.g. `2026.05.0`) | Never (pinned) | Fully reproducible environments where no changes are acceptable |

:::note
As of May 2026, `latest` was changed to mirror `stable` and is only updated on official tagged releases. If you previously relied on `latest` for the most recent unreleased changes, switch to the `dev` tag.
:::

Visit the [LocalStack for AWS tag](https://hub.docker.com/r/localstack/localstack-pro/tags?page=1&ordering=last_updated) page on Docker Hub.
35 changes: 14 additions & 21 deletions src/content/docs/aws/getting-started/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,10 @@ Across our docs, we use `localhost.localstack.cloud:4566` instead of `localhost:

### How should I use the latest LocalStack Docker images?

:::note
As of May 2026, the `latest` tag mirrors `stable` and is only updated on official releases. If you need the most recent unreleased changes, pull `localstack/localstack:dev` instead.
:::

To use the latest LocalStack Docker images, you either run `docker pull localstack/localstack:latest` or use the `docker-compose pull` if the image is set to `localstack/localstack:latest`.
You can also specify a particular digest to make sure you are using the correct image, like this: `localstack/localstack:latest@sha256:f803cc657843c6c7acf2631d15600783c3593e496fba418415afc87680d9d5bc`.

Expand All @@ -68,27 +72,16 @@ The diagnose endpoint is only available if you run LocalStack with `DEBUG=1`.

### What do the tags of the LocalStack Docker images mean?

We do push a set of different image tags for the LocalStack Docker images.
When using LocalStack, you can decide which tag you want to use.
These tags have different semantics and will be updated on different occasions:

- `latest` (default)
- This is our default tag.
It refers to the latest commit which has been fully tested using our extensive integration test suite.
- This also entails changes that are part of major releases, which means that this tag can contain breaking changes.
- This tag should be used if you want to stay up-to-date with the latest changes.
- `stable`
- This tag refers to the latest tagged release.
It will be updated with every release of LocalStack.
- This also entails major releases, which means that this tag can contain breaking changes.
- This tag should be used if you want to stay up-to-date with releases, but don't necessarily need the latest and greatest changes right away.
- `<YYYY.MM>` (e.g., `2026.03`)
- These tags can be used to refer to the latest release of a month. It will be updated with every patch release within this month.
- This tag can be used if you want to avoid any bigger changes, like new features, but still want to update to the latest bugfix release.
- `<YYYY.MM.patch>` (e.g., `2026.03.0`)
- These tags can be used if you want to use a very specific release.
It will not be updated.
- This tag can be used if you really want to avoid any changes to the image (not even minimal bug fixes).
We publish a set of image tags with different semantics, updated on different occasions:

- **`latest`**: Updated only on official tagged releases (e.g. `2026.05.0`). Equivalent to `stable`. Recommended for most users who want a stable, release-quality image. As of May 2026, this tag no longer tracks untagged commits on `main`, use `dev` for that behavior.
Copy link
Copy Markdown

@aidehn aidehn May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a similar comment on the release notes, it could be beneficial to give an example of a patch too (for that monthly version) to show this also includes patches for that monthly release!

... only on official tagged releases (e.g. `2026.05.0`, `2026.05.1`)

- **`stable`**: Same as `latest`. Updated with every official release.
- **`dev`**: Contains all merged, untagged commits from the `main` branch. Use this if you want the latest unreleased changes.
- **`nightly`**: Pushed from scheduled nightly builds. Useful for CI pipelines that benefit from a fresh build on a predictable cadence.
- **`YYYY.MM`** (e.g. `2026.05`): Updated with each patch release within that month. Use this to avoid feature changes while still receiving bugfixes.
Copy link
Copy Markdown

@aidehn aidehn May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I would potentially avoid the term "bugfixes" here when talking about patch versions as the patch releases main purpose is to provide security fixes and dependency updates! (not something to mention here, but we generally avoid making any functionality changes in these patch releases unless essential 👍🏼 )

- **`YYYY.MM.patch`** (e.g. `2026.05.0`): Pinned to an exact release and never updated. Use this for fully reproducible environments where even minor bugfix changes are undesirable.

Starting with the end-of-March 2026 release, LocalStack follows [calendar versioning](https://calver.org/) for official releases. For releases up to and including `v4.14.0`, tags follow Semantic Versioning.

Starting with the end-of-March 2026 release, LocalStack follows [calendar versioning](https://calver.org/) for official releases.

Expand Down
12 changes: 10 additions & 2 deletions src/content/docs/azure/getting-started/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,16 @@ $ docker-compose up
### Updating

To update the Azure Docker container, pull the latest image and restart the container.
The `latest` tag is the nightly build of the Azure Docker image.

The following tags are available for the LocalStack for Azure Docker image:

| Tag | Updated when | Recommended for |
|---|---|---|
| `latest` / `stable` | Tagged releases only (e.g. `2026.05.0`) | Most users — stable, release-quality builds |
| `dev` | Every merged commit on `main` | Users who need the latest unreleased changes |
| `nightly` | Scheduled nightly builds | CI pipelines that need a fresh build on a regular cadence |
| `YYYY.MM.patch` (e.g. `2026.05.0`) | Never (pinned) | Fully reproducible environments where no changes are acceptable |
Copy link
Copy Markdown

@aidehn aidehn May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Azure is an odd one since they don't have a tagged release process their definitions for each are different!

  1. For Azure, latest == dev - it is the latest commit from main
  2. There are no stable tags since they don't support a tagged release process (stable is only updated in these scenarios)
  3. There are also no YYYY.MM.patch, YYYY.MM and YYYY tags for the same reason as the above

So, overall we just need latest, nightly and dev and dev == latest!


Starting with the end-of-March 2026 release, versioned Azure image tags follow
[calendar versioning](https://calver.org/) in the `YYYY.MM.patch` format (for example, `2026.03.0`).
Refer to the available [tags on Docker Hub](https://hub.docker.com/r/localstack/localstack-azure-alpha/tags) for the latest releases.
Refer to the available [tags on Docker Hub](https://hub.docker.com/r/localstack/localstack-azure-alpha/tags) for the latest releases.
18 changes: 11 additions & 7 deletions src/content/docs/snowflake/getting-started/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,24 +143,28 @@ Expected response:
{ "success": true }
```


## Updating LocalStack

To keep both the CLI and emulator images up to date, run:

```bash
```shell
localstack update all
```

If you only want to update the Snowflake image manually (e.g. to pick up a recent fix), you can run:
If you want to pull a specific image tag manually, the following tags are available for the LocalStack for Snowflake Docker image:

```bash
docker pull localstack/snowflake:latest
```
| Tag | Updated when | Recommended for |
|---|---|---|
| `latest` / `stable` | Tagged releases only (e.g. `2026.05.0`) | Most users — stable, release-quality builds |
Copy link
Copy Markdown

@aidehn aidehn May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Snowflake has the same definitions as AWS so all good here, but nightly isn't supported just because the repo doesn't currently run the workflows every night - this can be updated for customers without the need for a release though if we wish for this to be the case 👍🏼 /cc @remotesynth

| `dev` | Every merged commit on `main` | Users who need the latest unreleased changes |
| `nightly` | Scheduled nightly builds | CI pipelines that need a fresh build on a regular cadence |
| `YYYY.MM.patch` (e.g. `2026.05.0`) | Never (pinned) | Fully reproducible environments where no changes are acceptable |

Starting with the end-of-March 2026 release, versioned Snowflake image tags follow
[calendar versioning](https://calver.org/) in the `YYYY.MM.patch` format (for example, `2026.03.0`).
Starting with the end-of-March 2026 release, versioned Snowflake image tags follow [calendar versioning](https://calver.org/) in the `YYYY.MM.patch` format (for example, `2026.03.0`).
Refer to the available [tags on Docker Hub](https://hub.docker.com/r/localstack/snowflake/tags) for the latest releases.


## Alternatives

If you prefer Docker Compose, you can start the emulator using the configuration below:
Expand Down