Skip to content

Commit 8aca387

Browse files
quetzalliwritesquetzalliwrites
authored
docs: updating docker tags and defining them (#664)
1 parent 7237925 commit 8aca387

4 files changed

Lines changed: 48 additions & 37 deletions

File tree

‎src/content/docs/aws/capabilities/config/docker-images.md‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,20 @@ While configuring to run LocalStack with Docker or Docker Compose, run the `loca
2929

3030
## Image tags
3131

32-
Starting with the end-of-March 2026 release, LocalStack version tags follow
33-
[calendar versioning](https://calver.org/) in the `YYYY.MM.patch` format (for example, `2026.03.0`).
32+
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).
3433

35-
Releases up to and including `v4.14.0` use [semantic versioning](https://semver.org).
36-
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.
37-
We intend to announce more significant features and enhancements during major & minor releases.
38-
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`).
34+
The following tags are available for the LocalStack Docker image:
3935

40-
Visit the [LocalStack for AWS tag](https://hub.docker.com/r/localstack/localstack-pro/tags?page=1&ordering=last_updated) in Docker Hub pages.
36+
| Tag | Updated when | Recommended for |
37+
|---|---|---|
38+
| `latest` / `stable` | Tagged releases only (e.g. `2026.05.0`) | Most users — stable, release-quality builds |
39+
| `dev` | Every merged commit on `main` | Users who need the latest unreleased changes |
40+
| `nightly` | Scheduled nightly builds | CI pipelines that need a fresh build on a regular cadence |
41+
| `YYYY.MM` (e.g. `2026.05`) | Each patch release within that month | Users who want bugfixes but want to avoid feature changes |
42+
| `YYYY.MM.patch` (e.g. `2026.05.0`) | Never (pinned) | Fully reproducible environments where no changes are acceptable |
43+
44+
:::note
45+
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.
46+
:::
47+
48+
Visit the [LocalStack for AWS tag](https://hub.docker.com/r/localstack/localstack-pro/tags?page=1&ordering=last_updated) page on Docker Hub.

‎src/content/docs/aws/getting-started/faq.mdx‎

Lines changed: 14 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,10 @@ Across our docs, we use `localhost.localstack.cloud:4566` instead of `localhost:
6060

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

63+
:::note
64+
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.
65+
:::
66+
6367
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`.
6468
You can also specify a particular digest to make sure you are using the correct image, like this: `localstack/localstack:latest@sha256:f803cc657843c6c7acf2631d15600783c3593e496fba418415afc87680d9d5bc`.
6569

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

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

71-
We do push a set of different image tags for the LocalStack Docker images.
72-
When using LocalStack, you can decide which tag you want to use.
73-
These tags have different semantics and will be updated on different occasions:
74-
75-
- `latest` (default)
76-
- This is our default tag.
77-
It refers to the latest commit which has been fully tested using our extensive integration test suite.
78-
- This also entails changes that are part of major releases, which means that this tag can contain breaking changes.
79-
- This tag should be used if you want to stay up-to-date with the latest changes.
80-
- `stable`
81-
- This tag refers to the latest tagged release.
82-
It will be updated with every release of LocalStack.
83-
- This also entails major releases, which means that this tag can contain breaking changes.
84-
- 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.
85-
- `<YYYY.MM>` (e.g., `2026.03`)
86-
- 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.
87-
- 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.
88-
- `<YYYY.MM.patch>` (e.g., `2026.03.0`)
89-
- These tags can be used if you want to use a very specific release.
90-
It will not be updated.
91-
- This tag can be used if you really want to avoid any changes to the image (not even minimal bug fixes).
75+
We publish a set of image tags with different semantics, updated on different occasions:
76+
77+
- **`latest`**: Updated only on official tagged releases (e.g. `2026.05.0`, `2026.05.1`). 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.
78+
- **`stable`**: Same as `latest`. Updated with every official release.
79+
- **`dev`**: Contains all merged, untagged commits from the `main` branch. Use this if you want the latest unreleased changes.
80+
- **`nightly`**: Pushed from scheduled nightly builds. Useful for CI pipelines that benefit from a fresh build on a predictable cadence.
81+
- **`YYYY.MM`** (e.g. `2026.05`): Updated with each patch release within that month. Use this to get the latest security fixes and dependency updates.
82+
- **`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.
83+
84+
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.
9285

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

‎src/content/docs/azure/getting-started/index.mdx‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,8 +77,15 @@ $ docker-compose up
7777
### Updating
7878

7979
To update the Azure Docker container, pull the latest image and restart the container.
80-
The `latest` tag is the nightly build of the Azure Docker image.
80+
81+
The following tags are available for the LocalStack for Azure Docker image:
82+
83+
| Tag | Updated when | Recommended for |
84+
|---|---|---|
85+
| `latest` | Tagged releases only (e.g. `2026.05.0`) | Most users, stable, release-quality builds |
86+
| `dev` | Every merged commit on `main` | Users who need the latest unreleased changes |
87+
| `nightly` | Scheduled nightly builds | CI pipelines that need a fresh build on a regular cadence |
8188

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

‎src/content/docs/snowflake/getting-started/index.mdx‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -143,24 +143,27 @@ Expected response:
143143
{ "success": true }
144144
```
145145

146+
146147
## Updating LocalStack
147148

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

150-
```bash
151+
```shell
151152
localstack update all
152153
```
153154

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

156-
```bash
157-
docker pull localstack/snowflake:latest
158-
```
157+
| Tag | Updated when | Recommended for |
158+
|---|---|---|
159+
| `latest` / `stable` | Tagged releases only (e.g. `2026.05.0`) | Most users — stable, release-quality builds |
160+
| `dev` | Every merged commit on `main` | Users who need the latest unreleased changes |
161+
| `YYYY.MM.patch` (e.g. `2026.05.0`) | Never (pinned) | Fully reproducible environments where no changes are acceptable |
159162

160-
Starting with the end-of-March 2026 release, versioned Snowflake image tags follow
161-
[calendar versioning](https://calver.org/) in the `YYYY.MM.patch` format (for example, `2026.03.0`).
163+
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`).
162164
Refer to the available [tags on Docker Hub](https://hub.docker.com/r/localstack/snowflake/tags) for the latest releases.
163165

166+
164167
## Alternatives
165168

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

0 commit comments

Comments
 (0)