diff --git a/content/en/tutorials/ephemeral-application-previews/index.md b/content/en/tutorials/ephemeral-application-previews/index.md index f3c582d924..f54b06d40d 100644 --- a/content/en/tutorials/ephemeral-application-previews/index.md +++ b/content/en/tutorials/ephemeral-application-previews/index.md @@ -21,7 +21,7 @@ leadimage: "ephemeral-application-previews-banner.png" ## Introduction -LocalStack's core cloud emulator allows you set up your cloud infrastructure on your local machine. +LocalStack's core cloud emulator allows you to set up your cloud infrastructure on your local machine. You can access databases, queues, and other managed services without needing to connect to a remote cloud provider. This speeds up your Software Development Life Cycle (SDLC) by making development and testing more efficient. Despite this, you still need a staging environment to do final acceptance tests before deploying your application to production. @@ -29,8 +29,8 @@ Despite this, you still need a staging environment to do final acceptance tests In many cases, staging environments are costly and deploying changes to them takes a lot of time. Also, teams can only use one staging environment at a time, which makes it difficult to test changes quickly. -With LocalStack's Ephemeral Instances, you can create short-lived, self-contained deployments of LocalStack in the cloud. -These Ephemeral Instances let you deploy your application on a remote LocalStack container, creating an Application Preview. +With LocalStack's [Ephemeral Instances](/user-guide/cloud-sandbox/ephemeral-instance/), you can create short-lived, self-contained deployments of LocalStack in the cloud. +These Ephemeral Instances also let you deploy your application on a remote LocalStack container, creating an [Application Preview](/user-guide/cloud-sandbox/application-previews/). This allows you to run end-to-end tests, preview features, and collaborate within your team or across teams asynchronously. This tutorial will show you how to use LocalStack's Ephemeral Instance feature to generate an Application Preview automatically for every new Pull Request (PR) using a GitHub Action workflow. @@ -96,7 +96,7 @@ on: This configuration ensures that every time a pull request is raised, the action is triggered. -A new job named `preview` specifies the GitHub-hosted runner to execute our workflow steps, while checking out the code: +A new job named `preview` specifies the GitHub-hosted runner to execute our workflow steps, while also checking out the code we need to deploy to the application preview instance: ```yaml jobs: @@ -114,7 +114,7 @@ jobs: To deploy the application preview, you can utilize the `LocalStack/setup-localstack/ephemeral/startup` action, which requires the following parameters: - `github-token`: Automatically configured on the GitHub Action runner. -- `localstack-api-key`: Configuration of a LocalStack CI key (`LOCALSTACK_API_KEY`) to activate licensed features in LocalStack. +- `localstack-api-key`: Configuration of a LocalStack [CI key](https://app.localstack.cloud/workspace/ci-keys) (`LOCALSTACK_API_KEY`) to activate licensed features in LocalStack (Note: You may need administrator permission to access creating new CI keys or legacy API keys). - `preview-cmd`: The set of commands necessary to deploy the application, including its infrastructure, on LocalStack. The following step sets up the dependencies and deploys the application preview on an ephemeral LocalStack instance: @@ -169,6 +169,7 @@ Follow these steps to add your LocalStack CI key to your forked GitHub repositor - Scroll down to the **Generate CI Key** card, where you can provide a name, and click **Generate CI Key** to receive a new key. - In your [GitHub repository secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions), set the **Name** as `LOCALSTACK_API_KEY` and the **Secret** as the CI Key. +If you do not have access to creating CI keys, contact your LocalStack account administrator. Now, you can commit and push your workflow to your forked GitHub repository. ### Run the GitHub Action workflow diff --git a/content/en/user-guide/cloud-sandbox/application-previews/index.md b/content/en/user-guide/cloud-sandbox/application-previews/index.md index 2288a79624..1b8f68d05b 100644 --- a/content/en/user-guide/cloud-sandbox/application-previews/index.md +++ b/content/en/user-guide/cloud-sandbox/application-previews/index.md @@ -7,7 +7,8 @@ description: Create an Application Preview to deploy your application changes in ## Introduction -Application Preview generates a preview environment from GitHub Pull Requests (PRs). +Application Preview generates a preview environment from GitHub Actions workflows. +For example, you can create a preview URL for every GitHub Pull Request (PRs). It allows temporary deployment of AWS powered applications on a LocalStack Ephemeral Instance to preview changes. This feature is currently only available for GitHub repositories that use GitHub Actions. @@ -30,10 +31,13 @@ We will configure a CI pipeline that runs on pull requests using GitHub Actions. To create an Application Preview, use the [`LocalStack/setup-localstack` action](https://github.com/localstack/setup-localstack). Create a file named `preview-pipeline.yml` in the `.github/workflows` directory of your custom repository. -This file should contain the CI pipeline that activates on every pull request. +The example below contains the details that can be used for a step in an existing CI pipeline that activates on every pull request. -The pipeline deploys the application to a LocalStack Ephemeral Instance using a `deploy.sh` script or similar for full application deployment. -A comment containg the preview link is automatically added to a Pull Request when created. +The pipeline deploys the application to a LocalStack Ephemeral Instance. +The steps necessary for building and deploying the application to LocalStack should be listed within the `preview-cmd` property. +The example below aggregates these steps into a single deployment script called `deploy.sh`. +A comment containing the preview link is automatically added to a Pull Request when created. +This preview is available for 30 minutes ```yaml uses: LocalStack/setup-localstack@v0.2.2 @@ -49,11 +53,17 @@ env: LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }} ``` -You must also set the `LOCALSTACK_API_KEY` as a repository secret, available from the [LocalStack Web Application](https://app.localstack.cloud/account/apikeys). +The `LOCALSTACK_API_KEY` must be set as a repository secret. +You can create a [CI key](https://app.localstack.cloud/workspace/ci-keys) via the LocalStack Web Application (note that you may need permission from your administrator to access this capability). +To add this secret to a GitHub repository, go to the "Settings" tab and then on the left-hand navigation choose "Secrets and variables" and then "Actions". The `GITHUB_TOKEN` is automatically generated by GitHub and requires no further configuration. ### Stop the Application Preview +It's important to understand that the ephemeral instance that powers the application preview is created _before_ the steps in the `preview-cmd` are run. +If the `preview-cmd` fails to complete successfully, the ephemeral instance will still be running on your account. +To address this, you can create an additional workflow step that shuts down the ephemeral instance if the workflow run fails (see the [GitHub Actions documentation](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#running-a-workflow-based-on-the-conclusion-of-another-workflow) for help in determining whether a workflow completed successfully). + To stop the Application Preview, you can configure the `state-action` to `stop`. ```yaml @@ -76,7 +86,7 @@ env: | `state-backend` | Starts an Application Preview, used with `state-action` to manage state | `ephemeral` | | `state-action` | Commands `start`/`stop` for managing Application Previews | | | `skip-ephemeral-stop` | Option to bypass stopping the Application Preview | `false` | -| `preview-cmd` | Commands to generate an Application Preview of the PR (supports `$AWS_ENDPOINT_URL`) | | +| `preview-cmd` | Commands to generate the application Preview of the PR (supports `$AWS_ENDPOINT_URL`) | | ## Overriding the Application Preview URL