Skip to content

revamp app preview docs #1397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 23, 2024
Merged

revamp app preview docs #1397

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3e51a3b
revamp app preview docs
HarshCasper Jul 22, 2024
5e6c668
Update content/en/user-guide/cloud-sandbox/application-previews/index.md
HarshCasper Jul 23, 2024
f3456c6
add note on override url
HarshCasper Jul 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions content/en/user-guide/cloud-sandbox/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 >}}
144 changes: 62 additions & 82 deletions content/en/user-guide/cloud-sandbox/application-previews/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,116 +7,96 @@ 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 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.
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/)
- [GitHub Account](https://github.com)

### 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).
To create an Application Preview, use the [`LocalStack/setup-localstack` 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.
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 workflow file to create the Application Preview looks like this:
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
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_/"
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).
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.

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.
### Stop the Application Preview

The workflow file to attach the Preview URL looks like this:
To stop the Application Preview, you can configure the `state-action` to `stop`.

```yaml
name: Finalize PR Preview

on:
workflow_run:
workflows: ["Create PR Preview"]
types:
- completed

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
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

| 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`) | |

## Overriding the Application Preview URL

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.
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;
```

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)