From 3e51a3b5dc7001fc5a8cd65f7fe28884edc37279 Mon Sep 17 00:00:00 2001 From: Harsh Mishra Date: Mon, 22 Jul 2024 21:42:18 +0530 Subject: [PATCH 1/3] revamp app preview docs --- .../application-previews/index.md | 137 +++++++----------- 1 file changed, 49 insertions(+), 88 deletions(-) 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 54322ee68d..ca5d9c9bb4 100644 --- a/content/en/user-guide/cloud-sandbox/application-previews/index.md +++ b/content/en/user-guide/cloud-sandbox/application-previews/index.md @@ -7,23 +7,19 @@ description: Create an Application Preview to deploy your application changes in ## Introduction -Application Preview allows you to generate an preview environment from GitHub Pull Request (PR) builds. -You can use Application Preview to temporarily deploy your AWS-powered application to a LocalStack Ephemeral Instance and preview your application changes. -Currently, the Application Preview are only supported for GitHub repositories using GitHub Actions. +Application Preview generates a preview environment from GitHub Pull Requests (PRs). +It allows temporary deployment of AWS or Snowflake powered applications on a LocalStack Ephemeral Instance to preview changes. +This feature is currently only available for GitHub repositories that use GitHub Actions. {{< callout >}} -Application Preview is currently available on invite-only preview. -If you'd like to try it out, please [contact us](https://www.localstack.cloud/demo) to request access. +Ephemeral Instances is offered as a **preview** feature and under active development. {{< /callout >}} ## Getting started -This guide is designed for users new to Application Preview and assumes basic knowledge of GitHub Actions. +This guide is designed for users new to Application Preview and assumes basic knowledge of GitHub Actions. We will configure a CI pipeline that runs on pull requests using GitHub Actions. -To get started with a ready-to-use template, you can fork the [`bref-localstack-sample`](https://github.com/localstack-samples/bref-localstack-sample) repository. -The sample application deploys a serverless PHP application using Bref and the Serverless Framework. - ### Prerequisites - [LocalStack Account](https://app.localstack.cloud/) @@ -31,92 +27,57 @@ The sample application deploys a serverless PHP application using Bref and the S ### Create the Application Preview -To create an Application Preview, you can use the [`LocalStack/setup-localstack/ephemeral/startup` action](https://github.com/localstack/setup-localstack). - -The sample repository has been configured to use the workflow described above. -For your custom repository, create a new file named `ci-pipeline.yml` in the `.github/workflows` directory. -This file will contain the CI pipeline that runs on every pull request. -This pipeline deploys the application to a LocalStack Ephemeral Instance. - -The workflow file to create the Application Preview looks like this: - -```yaml -name: Create PR Preview - -on: - pull_request: - types: [opened, synchronize, reopened] - -jobs: - test: - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Deploy Preview - uses: LocalStack/setup-localstack@v0.2.2 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - localstack-api-key: ${{ secrets.LOCALSTACK_API_KEY }} - preview-cmd: | - # Add your custom deployment commands here. - # Below is an example for the Bref Serverless application. - export AWS_DEFAULT_REGION=us-east-1 - npm install --include=dev - npm run build - composer require bref/bref - mv .env.example .env - php artisan key:generate - npm run serverless -- deploy --stage dev - - pip install awscli-local[ver1] - apiId=$(awslocal apigatewayv2 get-apis| jq -r '.Items[0].ApiId') - echo "Open URL: $AWS_ENDPOINT_URL/restapis/$apiId/dev/_user_request_/" +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 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. + +```yaml +uses: LocalStack/setup-localstack@v0.2.2 +with: + github-token: ${{ secrets.GITHUB_TOKEN }} + state-backend: ephemeral + state-action: start + # Adding this option prevents Ephemeral Instance to be stopped after the `preview-cmd` run + skip-ephemeral-stop: 'true' + # Optional script/command to run + preview-cmd: deploy.sh +env: + LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }} ``` -You will also need to configure the `LOCALSTACK_API_KEY` as a repository secret. -You can find the API key on the [LocalStack Web Application](https://app.localstack.cloud/account/apikeys). -The `GITHUB_TOKEN` is automatically created by GitHub and you can use it without any additional configuration. - -### Attach the Preview URL - -You can now attach the Preview URL to the pull request by using the [`LocalStack/setup-localstack/finish` action](https://github.com/localstack/setup-localstack). - -The sample repository has been configured to use the workflow described above. -For your custom repository, create a new file named `ci-finalize.yml` in the `.github/workflows` directory. -This file contains the CI pipeline that attaches a comment to the pull request with the Preview URL of the deployed application. - -The workflow file to attach the Preview URL looks like this: +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 `GITHUB_TOKEN` is automatically generated by GitHub and requires no further configuration. -```yaml -name: Finalize PR Preview +### Stop the Application Preview -on: - workflow_run: - workflows: ["Create PR Preview"] - types: - - completed +To stop the Application Preview, you can configure the `state-action` to `stop`. -jobs: - test: - runs-on: ubuntu-latest - steps: - - name: Finalize PR comment - uses: LocalStack/setup-localstack/finish@v0.2.0 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - include-preview: true +```yaml +uses: LocalStack/setup-localstack@v0.2.2 +with: + github-token: ${{ secrets.GITHUB_TOKEN }} + state-backend: ephemeral + state-action: stop +env: + LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }} ``` -### Open a Pull Request +## Configuration -Once your changes are in your repository, open a new pull request. -GitHub will receive the request and trigger your workflow. -You can track the workflow's status and logs in the **Checks** section of the pull request. +| Input | Description | Default | +|------------------------------|---------------------------------------------------------------------------|--------------| +| `auto-load-pod` | Specifies which Cloud Pod to load during LocalStack startup | `None` | +| `extension-auto-install` | Defines which extensions to install during LocalStack startup for Application Previews | `None` | +| `lifetime` | Duration an Application Preview remains active | 30 | +| `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`) | | -After a short delay, the workflow will update the pull request with the URL of your preview environment. -Just click on it to see the changes in real-time. +## Examples -Each time the branch is updated, the same workflow will automatically refresh the preview environment. +- [Creating ephemeral application previews with LocalStack and GitHub Actions](https://docs.localstack.cloud/tutorials/ephemeral-application-previews/) and the [example repository](https://github.com/localstack-samples/sample-notes-app-dynamodb-lambda-apigateway) From 5e6c668878bb1fff0205e0f4f2f9696cb221b3c5 Mon Sep 17 00:00:00 2001 From: Harsh Mishra Date: Tue, 23 Jul 2024 17:29:58 +0530 Subject: [PATCH 2/3] Update content/en/user-guide/cloud-sandbox/application-previews/index.md Co-authored-by: lukqw <39307517+lukqw@users.noreply.github.com> --- .../en/user-guide/cloud-sandbox/application-previews/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 ca5d9c9bb4..f07276b038 100644 --- a/content/en/user-guide/cloud-sandbox/application-previews/index.md +++ b/content/en/user-guide/cloud-sandbox/application-previews/index.md @@ -8,7 +8,7 @@ description: Create an Application Preview to deploy your application changes in ## Introduction Application Preview generates a preview environment from GitHub Pull Requests (PRs). -It allows temporary deployment of AWS or Snowflake powered applications on a LocalStack Ephemeral Instance to preview changes. +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. {{< callout >}} From f3456c6332f176afe1fa7e4f6c598e555c5f2e83 Mon Sep 17 00:00:00 2001 From: HarshCasper Date: Tue, 23 Jul 2024 18:11:47 +0530 Subject: [PATCH 3/3] add note on override url --- content/en/user-guide/cloud-sandbox/_index.md | 3 +- .../application-previews/index.md | 39 ++++++++++++++----- 2 files changed, 30 insertions(+), 12 deletions(-) diff --git a/content/en/user-guide/cloud-sandbox/_index.md b/content/en/user-guide/cloud-sandbox/_index.md index f30ea8fff7..9544fb0cc2 100644 --- a/content/en/user-guide/cloud-sandbox/_index.md +++ b/content/en/user-guide/cloud-sandbox/_index.md @@ -18,6 +18,5 @@ LocalStack Cloud Sandbox encompasses the following features: - Facilitate collaboration by allowing developers to test features on the same environment. {{< callout >}} -Cloud Sandbox is currently available on invite-only preview. -If you'd like to try it out, please [contact us](https://www.localstack.cloud/demo) to request access. +Cloud Sandbox is offered as a **preview** feature and under active development. {{< /callout >}} 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 f07276b038..9288a2def9 100644 --- a/content/en/user-guide/cloud-sandbox/application-previews/index.md +++ b/content/en/user-guide/cloud-sandbox/application-previews/index.md @@ -7,8 +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). -It allows temporary deployment of AWS powered applications on a LocalStack Ephemeral Instance to preview changes. +Application Preview generates a preview environment from GitHub Pull Requests (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. {{< callout >}} @@ -17,7 +17,7 @@ Ephemeral Instances is offered as a **preview** feature and under active develop ## Getting started -This guide is designed for users new to Application Preview and assumes basic knowledge of GitHub Actions. +This guide is designed for users new to Application Preview and assumes basic knowledge of GitHub Actions. We will configure a CI pipeline that runs on pull requests using GitHub Actions. ### Prerequisites @@ -29,13 +29,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. +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 pipeline deploys the application to a LocalStack Ephemeral Instance using a `deploy.sh` script or similar for full application deployment. +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. -```yaml +```yaml uses: LocalStack/setup-localstack@v0.2.2 with: github-token: ${{ secrets.GITHUB_TOKEN }} @@ -49,14 +49,14 @@ 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). +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 `GITHUB_TOKEN` is automatically generated by GitHub and requires no further configuration. -### Stop the Application Preview +### Stop the Application Preview To stop the Application Preview, you can configure the `state-action` to `stop`. -```yaml +```yaml uses: LocalStack/setup-localstack@v0.2.2 with: github-token: ${{ secrets.GITHUB_TOKEN }} @@ -78,6 +78,25 @@ env: | `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`) | | +## Overriding the Application Preview URL + +The Application Preview URL is automatically generated and added as a comment to the Pull Request. +However, if your application is served on a different URL, you can override the URL using the `LS_PREVIEW_URL`. +It is beneficial if you are using a CloudFront distribution or a custom domain. + +Here is an example of how to override the URL: + +```yaml +preview-cmd: | + make build; + make bootstrap; + make deploy; + make build-frontend; + make deploy-frontend; + distributionId=$(awslocal cloudfront list-distributions | jq -r '.DistributionList.Items[0].Id'); + echo LS_PREVIEW_URL=$AWS_ENDPOINT_URL/cloudfront/$distributionId/ >> $GITHUB_ENV; +``` + ## Examples - [Creating ephemeral application previews with LocalStack and GitHub Actions](https://docs.localstack.cloud/tutorials/ephemeral-application-previews/) and the [example repository](https://github.com/localstack-samples/sample-notes-app-dynamodb-lambda-apigateway)