update docs with new license management flow and UX (#864)

Co-authored-by: HarshCasper <[email protected]>
localstack · Nov 16, 2023 · e72c11c · e72c11c
1 parent 383e6d6
commit e72c11c
Show file tree

Hide file tree

Showing 52 changed files with 428 additions and 193 deletions.
diff --git a/.github/workflows/markdown.links.config.json b/.github/workflows/markdown.links.config.json
@@ -1,5 +1,8 @@
 {
     "ignorePatterns": [
+        {
+            "pattern": "https://localstack.cloud/(.*)"
+        },
         {
             "pattern": "https://kinesis.us-east-1.amazonaws.com/"
         },

diff --git a/content/en/getting-started/api-key.md b/content/en/getting-started/api-key.md
@@ -8,6 +8,10 @@ aliases:
   - /get-started/pro/
 ---
 
+{{< alert title="Important" color="danger" >}}
+API Keys are being phased out for LocalStack activation, with a transition to Auth Tokens. Auth Tokens simplify license management and eliminate the need for developers to modify their setup when there are changes to licenses. Refer to our [Auth Token documentation]({{< ref "auth-token" >}}) for more information.
+{{< /alert >}}
+
 The LocalStack API key is a unique identifier to activate your LocalStack license needed to start LocalStack Pro.
 You can find your API key in the [LocalStack Web app](https://app.localstack.cloud/account/apikeys).
 This guide demonstrates how you can use your new LocalStack licenses and go over some best practices regarding the usage, activation, and safety of your LocalStack API key.

diff --git a/content/en/getting-started/auth-token.md b/content/en/getting-started/auth-token.md
@@ -0,0 +1,119 @@
+---
+title: "Auth Token"
+weight: 20
+description: >
+  Configure your auth token to start LocalStack
+---
+
+LocalStack uses auth tokens to to authenticate users and to activate your LocalStack license.
+You can find your auth token on the [Getting Started page in the web app](https://app.localstack.cloud/getting-started) or on the [Auth Token page](https://app.localstack.cloud/workspace/auth-token)
+
+## Managing your License
+
+To get started, you need to have a LocalStack license. If you don't have one, you can [sign up for a free trial](https://localstack.cloud/pricing/) without any credit card required. The free trial will last 14 days, and you can use it to test all the features of LocalStack.
+
+You can assign licenses to users on the [Users & Licenses](https://app.localstack.cloud/workspace/members) page or you can check your assigned license on the [My License](https://app.localstack.cloud/workspace/my-license) page.
+
+{{< alert title="Important" color="danger" >}}
+- Avoid sharing your auth token with anyone. Ensure that you do not commit it to any source code management systems (like Git repositories).
+- If you push an auth token to a public repository, it has potentially been exposed and might remain in the history (even if you try to rewrite it).
+- If you accidentally publish your auth token, you can rotate it on the [Auth Token](https://app.localstack.cloud/workspace/auth-token) page
+- Use in CI or other machine environments requires a CI key. Check out our [CI documentation]({{< ref "user-guide/ci" >}}) to see the proper way to handle secrets in your CI environment to store your CI key securely.
+{{< /alert >}}
+
+### Starting LocalStack via CLI
+
+LocalStack expects your auth token to be present in the environment variable `LOCALSTACK_AUTH_TOKEN`. You can define the `LOCALSTACK_AUTH_TOKEN` environment variable before or while starting LocalStack using the `localstack` CLI.
+
+{{< tabpane >}}
+{{< tab header="macOS/Linux" lang="shell" >}}
+export LOCALSTACK_AUTH_TOKEN=<YOUR_AUTH_TOKEN>
+localstack start
+{{< /tab >}}
+{{< tab header="Windows" lang="powershell" >}}
+$env:LOCALSTACK_AUTH_TOKEN="<YOUR_AUTH_TOKEN>"; localstack start
+{{< /tab >}}
+{{< /tabpane >}}
+
+You can optionally run your LocalStack container in background mode by adding the `-d` flag to the `localstack start` command.
+
+The `localstack` CLI will detect the auth token and properly pass it to the LocalStack container.
+
+{{< alert title="Note" >}}
+If you are using LocalStack with an auth token, you need to pull the [LocalStack Pro image](https://docs.localstack.cloud/references/docker-images/#localstack-pro-image) that includes the Pro services and several other advanced features.
+{{< /alert >}}
+
+### Starting LocalStack via Docker
+
+To start LocalStack using Docker, you have to specify the auth token using the `-e` flag for environment variables:
+
+{{< command "hl_lines=5" >}}
+$ docker run \
+  --rm -it \
+  -p 4566:4566 \
+  -p 4510-4559:4510-4559 \
+  -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:- } \
+  localstack/localstack-pro
+{{< / command >}}
+
+For more information about starting LocalStack with Docker, take a look at our [Docker installation](https://docs.localstack.cloud/getting-started/installation/#docker) guide.
+
+### Starting LocalStack via Docker-Compose
+
+To start LocalStack using `docker-compose`, you have to include the `LOCALSTACK_AUTH_TOKEN` environment variable in your `docker-compose.yml` file:
+
+```yaml
+environment:
+  - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN- }
+```
+
+You can set the auth token manually, or you can use the `export` command to set the auth token in your current shell session. The auth token will be passed into your LocalStack container, such that the key activation can take place.
+
+## Licensing-related configuration
+
+If you want to make sure that LocalStack is only started if you can activate LocalStack Pro or Enterprise, or if you wish to suppress licensing-related error messages, take a look at our [configuration guide]({{< ref "configuration.md#localstack-pro">}}) regarding LocalStack Pro.
+
+## Checking license activation
+
+The easiest way to check if LocalStack is activated is to query the health endpoint for a list of the running services:
+
+{{< command >}}
+$ curl localhost:4566/_localstack/health | jq
+{{< / command >}}
+
+If a Pro-only [service]({{< ref "aws" >}}) -- like [XRay]({{< ref "xray" >}}) -- is running, LocalStack has started successfully. You can also check the logs of the LocalStack container to see if the activation was successful.
+
+{{< command >}}
+[...] Successfully activated license
+{{< / command >}}
+
+Otherwise, check our collected most [common activation issues](#common-activation-issues).
+
+## Common activation issues
+
+Since LocalStack v2.0.0, the image `localstack/localstack-pro` requires a successful license activation to start.
+If the license activation fails, LocalStack will quit with an error messages that may look something like this:
+
+```bash
+===============================================
+License activation failed! 🔑❌
+
+Reason: The credentials defined in your environment are invalid. Please make sure to either set the LOCALSTACK_AUTH_TOKEN variable to a valid auth token, or the LOCALSTACK_API_KEY variable to a valid LocalStack API key. You can find your auth token or API key in the LocalStack web app https://app.localstack.cloud.
+
+Due to this error, Localstack has quit. LocalStack pro features can only be used with a valid license.
+
+- Please check that your credentials are set up correctly and that you have an active license.
+  You can find your credentials in our webapp at https://app.localstack.cloud.
+- If you want to continue using LocalStack without pro features you can set `ACTIVATE_PRO=0`.
+```
+
+There are several reasons a key activation can fail:
+* Missing credentials: Using `localstack/localstack-pro` requires per default to have an auth token or legacy API key set.
+* Invalid license: there is no valid license associated with your user account, for example because the license has expired.
+* License server cannot be reached: LocalStack will try to perform an offline license activation if the license server cannot be reached, but will require a re-activation every 24 hours.
+
+If you are using the `localstack/localstack-pro` image, but cannot activate your license, we recommend falling back to the community version `localstack/localstack`.
+If that is not an option, you can set `ACTIVATE_PRO=0` which will attempt to start LocalStack without pro features.
+
+Navigate to our [FAQ page]({{< ref "faq" >}}) if your are having troubles with the LocalStack license activation.
+If you have any further problems concerning your license activation, or if the steps do not help, do not hesitate to [contact us](https://localstack.cloud/contact/).
diff --git a/content/en/getting-started/faq.md b/content/en/getting-started/faq.md
@@ -3,7 +3,7 @@ title: "Frequently Asked Questions"
 linkTitle: "FAQ"
 weight: 40
 description: >
-  This page answers the frequently asked questions about LocalStack Pro, Enterprise, and Community Editions. 
+  This page answers the frequently asked questions about LocalStack Pro, Enterprise, and Community Editions.
 cascade:
   type: docs
 hide_readingtime: true
@@ -74,7 +74,7 @@ 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:
@@ -93,8 +93,8 @@ A company proxy can lead to connection issues. To allow access to the `localstac
 
 ```yaml
 ...
-environment: 
-- HTTP_PROXY = 
+environment:
+- HTTP_PROXY =
 - NO_PROXY = .s3.localhost.localstack.cloud,127.0.0.1,*.localhost
 ...
 ```
@@ -135,7 +135,7 @@ You might be able to connect to the internet, but your Docker container can't co
 
 More details can be found on [official docker documentation](https://docs.docker.com/network/bridge/#enable-forwarding-from-docker-containers-to-the-outside-world).
 
-Solution for this is enabling the IP forwarding: 
+Solution for this is enabling the IP forwarding:
 
 ```bash
 sudo sysctl -w net.ipv4.ip_forward=1
@@ -175,7 +175,7 @@ For example, these options may interfere with the functionality of AppSync funct
 We advise you to exercise caution.
 {{< /alert >}}
 
-You can change the LocalStack `volume` folder to use the WSL Linux file system instead of the Windows host folder.  
+You can change the LocalStack `volume` folder to use the WSL Linux file system instead of the Windows host folder.
 To do so, you need to change the [`docker-compose.yml`](https://github.com/localstack/localstack/blob/master/docker-compose-pro.yml) file and add the following lines:
 
 {{< tabpane text=true >}}
@@ -213,21 +213,21 @@ For more details visit [Docker WSL documentation](https://docs.docker.com/deskto
 
 ## LocalStack Platform FAQs
 
-### How do I check if my API key is valid and activated?
+### How do I check if my license is valid and activated?
 
 The easiest way to check if LocalStack Pro or Enterprise is activated is to check the health endpoint of LocalStack for a list of the running services:
 
 {{< command >}}
 $ 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 API key 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
-Activation key "abc..."(10) is invalid or expired! Reason: ...
+license activation failed! Reason: ...
 ```
 
-If this error occurs, something is wrong with your API key or license. Make sure your API key is set correctly (check for typos!) and your license is valid. If the API key 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?
 
@@ -269,7 +269,7 @@ Some corporate DNS servers might filter requests to certain domains. Contact you
 
 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? 
+### 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.
 

diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md
@@ -18,7 +18,7 @@ hide_readingtime: true
 | [Edge Port]({{< ref "endpoint-url" >}})                                   | The HTTP port LocalStack listens on for any type of request (e.g. from AWS SDKs). The default port is 4566.                                                                                                                                                                                     |
 | [External Service Ports]({{< ref "external-ports" >}})                    | The ports reserved for infrastructure that is started as part of a managed service like database server, Redis cluster, and are exposed through the LocalStack Container.                                                                                                                       |
 | [Lambda Hot Reloading]({{< ref "hot-reloading" >}})                       | The ability to make changes in Lambda handler files, and have them immediately reflected on each invocation of a Lambda function, without the need to redeploy the Lambda function.                                                                                                             |
-| [LocalStack API Key]({{< ref "api-key" >}})                               | An API key that can be configured via the LOCALSTACK_API_KEY environment variable, to enable advanced features in your LocalStack instance. We distinguish between individual developer keys, as well as CI keys for continuous integration environments (e.g., Github Actions, CircleCI, etc). |
+| [LocalStack auth token]({{< ref "auth-token" >}})                         | An auth token that can be configured via the LOCALSTACK_AUTH_TOKEN environment variable, to enable advanced features in your LocalStack instance. We distinguish between individual developer auth tokens, as well as CI keys for continuous integration environments (e.g., Github Actions, CircleCI, etc). |
 | [LocalStack Container]({{< ref "installation" >}})                        | The Docker/Podman container or Kubernetes pod running LocalStack.                                                                                                                                                                                                                               |
 | [LocalStack Extensions]({{< ref "references/extensions" >}})              | Extend and customize LocalStack using pluggable Python distributions to run applications alongside the main process in the LocalStack Docker container.                                                                                                                                         |
 | [LocalStack Platform]({{< ref "web-application" >}})                      | The LocalStack Web Application for licensed users to use advanced features, such as Stack Insights, CI Analytics, Resource Browser, and Team Collaboration.                                                                                                                                     |