add FAQ on Docker image tags (#1078)

* cleanup faq to use one line for each sentence

* add FAQ section on docker image tags

Author: alexrashed

content/en/getting-started/faq.md

@@ -13,7 +13,8 @@ hide_readingtime: true
 
 ### How to update my LocalStack CLI?
 
-If the LocalStack CLI version is heavily outdated, it might lead to issues with container startup and debug commands. If you are using an older version of LocalStack, you can update it by running the following command:
+If the LocalStack CLI version is heavily outdated, it might lead to issues with container startup and debug commands.
+If you are using an older version of LocalStack, you can update it by running the following command:
 
 {{< command >}}
 $ pip install --upgrade localstack localstack-ext
@@ -37,21 +38,51 @@ The primary reason being that some users are behind a corporate firewall or an i
 
 ### How should I use the latest LocalStack Docker images?
 
-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`.
+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`.
 
 You can also use the our diagnose endpoint (`http://localhost:4566/_localstack/diagnose`) to get the specific image hashes and compare them with the current (latest) images on [Docker Hub](https://hub.docker.com/r/localstack/).
 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.
+- `<major>` (e.g. `3`)
+  - These tags can be used to refer to the latest release of a specific major release.
+    It will be updated with every minor and patch release within this major release.
+  - This tag should be used if you want to avoid any potential breaking changes.
+- `<major>.<minor>` (e.g. `3.0`)
+  - These tags can be used to refer to the latest release of a specific minor release.
+    It will be updated with every patch release within this minor release.
+  - 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.
+- `<major>.<minor>.<patch>` (e.g. `3.0.2`)
+  - 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).
+
 ### How can I access LocalStack from an alternative computer?
 
-You can access LocalStack from an alternative computer, by exposing port `4566` to the public network interface (`0.0.0.0` instead of `127.0.0.1`) in your `docker-compose.yml` configuration. However, we do not recommend using this setup - for security reasons, as it exposes your local computer to potential attacks from the outside world.
+You can access LocalStack from an alternative computer, by exposing port `4566` to the public network interface (`0.0.0.0` instead of `127.0.0.1`) in your `docker-compose.yml` configuration.
+However, we do not recommend using this setup - for security reasons, as it exposes your local computer to potential attacks from the outside world.
 
 ### How to resolve Git Bash issues with LocalStack?
 
 If you're using Git Bash with LocalStack, you might encounter some issues.
 This is due to the automatic conversion of POSIX paths to Windows paths when command-line options start with a slash.
-For instance, `"/usr/bin/bash.exe"` would be converted to `"C:\Program Files\Git\usr\bin\bash.exe"`.  
-This conversion can cause problems when it's not needed, such as with `"--name /test/parameter/new"`.  
+For instance, `"/usr/bin/bash.exe"` would be converted to `"C:\Program Files\Git\usr\bin\bash.exe"`.
+This conversion can cause problems when it's not needed, such as with `"--name /test/parameter/new"`.
 To prevent this, you can temporarily set the `MSYS_NO_PATHCONV` environment variable.
 Another workaround is to double the first slash in your command to prevent the POSIX-to-Windows path conversion.
 
@@ -74,7 +105,8 @@ For additional known issues related to Git Bash, you can refer to the following
 
 ### How to fix LocalStack CLI (Python) UTF-8 encoding issue under Windows?
 
-If you are using LocalStack CLI under Windows, you might run into encoding issues. To fix this, set the following environment variables:
+If you are using LocalStack CLI under Windows, you might run into encoding issues.
+To fix this, set the following environment variables:
 Set the system locale (language for non-Unicode programs) to UTF-8 to avoid Unicode errors.
 
 Follow these steps:
@@ -89,7 +121,8 @@ If you would like to keep the system locale as it is, you can mitigate the issue
 
 ### How do I resolve connection issues with proxy blocking access to LocalStack's BigData image?
 
-A company proxy can lead to connection issues. To allow access to the `localstack/bigdata` image, use the following Docker configuration in your `docker-compose.yml` file:
+A company proxy can lead to connection issues.
+To allow access to the `localstack/bigdata` image, use the following Docker configuration in your `docker-compose.yml` file:
 
 ```yaml
 ...
@@ -101,7 +134,8 @@ environment:
 
 ### Why is it that LocalStack is unable to connect to internet?
 
-You might be able to connect to the internet, but your Docker container can't connect. This can affect start of LocalStack.
+You might be able to connect to the internet, but your Docker container can't connect.
+This can affect start of LocalStack.
 
 Please ensure that you are not using the `none` network driver when starting your docker container.
 More details about the default bridge network can be found on [official docker documentation](https://docs.docker.com/network/bridge).
@@ -129,7 +163,9 @@ Refer to our [network troubleshooting guide]({{< ref "references/network-trouble
 
 ### How to resolve the pull rate limit issue for LocalStack's Docker image?
 
-If you receive `ERROR: toomanyrequests: Too Many Requests.` when pulling the LocalStack Docker image, you have reached your pull rate limit. You may increase the limit by [authenticating and upgrading](https://www.docker.com/increase-rate-limits). Set your DockerHub credentials:
+If you receive `ERROR: toomanyrequests: Too Many Requests.` when pulling the LocalStack Docker image, you have reached your pull rate limit.
+You may increase the limit by [authenticating and upgrading](https://www.docker.com/increase-rate-limits).
+Set your DockerHub credentials:
 
 ```bash
 (sudo) docker login --username=yourUsername
@@ -146,7 +182,8 @@ You can add in the volume `~/.docker/config.json:/config.json` where the `con
 ...
 ```
 
-If you have an active AWS account, you can use the public AWS ECR image. You can use the following command to pull the image:
+If you have an active AWS account, you can use the public AWS ECR image.
+You can use the following command to pull the image:
 
 {{< tabpane >}}
 {{< tab header="Community" lang="shell" >}}
@@ -211,17 +248,23 @@ The easiest way to check if LocalStack Pro or Enterprise is activated is to chec
 $ curl localhost:4566/_localstack/health | jq
 {{< / command >}}
 
-If a Pro-only [service]({{< ref "aws" >}}) -- like [XRay]({{< ref "xray" >}}) -- is running, LocalStack Pro or Enterprise has started successfully. If your auth token is invalid, you will see an error message like this in the logs of LocalStack:
+If a Pro-only [service]({{< ref "aws" >}}) -- like [XRay]({{< ref "xray" >}}) -- is running, LocalStack Pro or Enterprise has started successfully.
+If your auth token is invalid, you will see an error message like this in the logs of LocalStack:
 
 ```bash
 license activation failed! Reason: ...
 ```
 
-If this error occurs, something is wrong with your auth token or license. Make sure your auth token is set correctly (check for typos!) and your license is valid. If the auth token still does not work, please [contact us](https://localstack.cloud/contact/).
+If this error occurs, something is wrong with your auth token or license.
+Make sure your auth token is set correctly (check for typos!) and your license is valid.
+If the auth token still does not work, please [contact us](https://localstack.cloud/contact/).
 
 ### How are CI credits in LocalStack calculated?
 
-A CI key allows you to use LocalStack in your CI environment. Every activation of a CI key consumes one build credit. This means that with every build triggered through the LocalStack container you will consume one credit. To understand the CI pricing across our product tiers, follow up with our [LocalStack in CI]({{<ref "user-guide/ci">}}) documentation.
+A CI key allows you to use LocalStack in your CI environment.
+Every activation of a CI key consumes one build credit.
+This means that with every build triggered through the LocalStack container you will consume one credit.
+To understand the CI pricing across our product tiers, follow up with our [LocalStack in CI]({{<ref "user-guide/ci">}}) documentation.
 
 ### What should I do if I cannot connect to LocalStack API?
 
@@ -233,7 +276,8 @@ WARNING:localstack_ext.bootstrap.licensing: Error activating API key "abc..."(10
 ConnectionRefusedError: [Errno 111] Connection refused
 ```
 
-LocalStack cannot contact our API to perform the license activation. Confirm with your network administrator that no policies block the connection to our backend.
+LocalStack cannot contact our API to perform the license activation.
+Confirm with your network administrator that no policies block the connection to our backend.
 
 ### What should I do if I cannot resolve `api.localstack.cloud`?
 
@@ -253,20 +297,28 @@ $ dig api.localstack.cloud
 
 If the result has some other status than `status: NOERROR,` your machine cannot resolve this domain.
 
-Some corporate DNS servers might filter requests to certain domains. Contact your network administrator to safelist` localstack.cloud` domains.
+Some corporate DNS servers might filter requests to certain domains.
+Contact your network administrator to safelist` localstack.cloud` domains.
 
 ### How does LocalStack Pro handle security patches and bug fixes?
 
-We take security seriously and respond to any emergency vulnerabilities as soon as possible. Our cloud provider (AWS) handles most of the infrastructure maintenance for us. We also use Infrastructure-as-Code scripts to ensure that our infrastructure configuration is consistent and recoverable in case of a disaster.
+We take security seriously and respond to any emergency vulnerabilities as soon as possible.
+Our cloud provider (AWS) handles most of the infrastructure maintenance for us.
+We also use Infrastructure-as-Code scripts to ensure that our infrastructure configuration is consistent and recoverable in case of a disaster.
 
 ### How does LocalStack ensure the security of its containers and images?
 
-Our software assets are regularly checked for vulnerabilities, such as code issues and outdated dependencies. We use Dependabot to scan our GitHub repositories, and Trivy as well as Snyk (among other security tools) to scan our Docker images.
+Our software assets are regularly checked for vulnerabilities, such as code issues and outdated dependencies.
+We use Dependabot to scan our GitHub repositories, and Trivy as well as Snyk (among other security tools) to scan our Docker images.
 
 ### Do you have any penetration test reports or SOC2 reports that demonstrate your security compliance?
 
-We conduct regular penetration tests and audits to ensure our services are secure and compliant. If you want to access our security documentation and test reports, please contact us at info@localstack.cloud, and we will be happy to share them with you.
+We conduct regular penetration tests and audits to ensure our services are secure and compliant.
+If you want to access our security documentation and test reports, please contact us at info@localstack.cloud, and we will be happy to share them with you.
 
 ### Does LocalStack provide offline capabilities?
 
-LocalStack Community and Pro/Team provide limited offline capabilities. To use a fully-fledged offline mode, you may use LocalStack Enterprise, which can be used in air-gapped environments. The regular LocalStack Docker images may need to download additional dependencies for specific services (e.g., Elasticsearch, Big Data services) at runtime, while the offline image bakes all dependencies into the image, along with any other configuration that you might need. For more details, please take a look at our [Enterprise offering](https://localstack.cloud/pricing).
+LocalStack Community and Pro/Team provide limited offline capabilities.
+To use a fully-fledged offline mode, you may use LocalStack Enterprise, which can be used in air-gapped environments.
+The regular LocalStack Docker images may need to download additional dependencies for specific services (e.g., Elasticsearch, Big Data services) at runtime, while the offline image bakes all dependencies into the image, along with any other configuration that you might need.
+For more details, please take a look at our [Enterprise offering](https://localstack.cloud/pricing).