rewrite cloud sandbox docs

content/en/user-guide/cloud-sandbox/_index.md

@@ -0,0 +1,17 @@
+---
+title: "Cloud Sandbox"
+linkTitle: "Cloud Sandbox"
+weight: 12
+description: >
+  You can run a LocalStack instance as a Cloud Sandbox and access it from your local machine.
+cascade:
+  type: docs
+---
+
+## Introduction
+
+LocalStack Cloud Sandbox allow you to run an LocalStack instance in the cloud. LocalStack Cloud Sandbox encompasses the following features:
+
+- Deploy LocalStack as an ephemeral instance for dev&test loops without running it locally.
+- Create easy previews by enabling preview-per-PR type workflows for application change.
+- Facilitate collaboration by allowing developers to test features on the same environment.

content/en/user-guide/cloud-sandbox/application-previews/index.md

@@ -0,0 +1,103 @@
+---
+title: "Application Preview"
+linkTitle: "Application Preview"
+weight: 2
+description: Create an Application Preview to deploy your application changes in an Ephemeral Instance!
+---
+
+## 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.
+
+## 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/preview` 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/preview@main
+        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_/"
+```
+
+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:
+
+```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@main
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          include-preview: true
+```
+
+### Open a Pull Request
+
+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.
+
+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.
+
+Each time the branch is updated, the same workflow will automatically refresh the preview environment.

content/en/user-guide/cloud-sandbox/ephemeral-instance/index.md

@@ -0,0 +1,70 @@
+---
+title: "Ephemeral Instances"
+linkTitle: "Ephemeral Instances"
+weight: 1
+description: Create an Ephemeral Instance in the cloud using the LocalStack Web Application!
+---
+
+## Introduction
+
+LocalStack Ephemeral Instance allows you to run an LocalStack instance in the cloud. You can interact with these remote instances via the LocalStack Web Application, or by configuring your integrations and developer tools with the endpoint URL of the remote instance.
+
+## Getting started
+
+This guide is designed for users new to Ephemeral Instance and assumes basic knowledge of the LocalStack Web Application. In this guide, we will create an Ephemeral Instance and interact with it via the LocalStack Web Application and the AWS CLI.
+
+### Create a new Ephemeral Instance
+
+Navigate to the [**LocalStack Instance Management**](https://app.localstack.cloud/instances) and click on the **Ephemeral (Team)** tab. Click on the **Create Ephemeral Instance** button.
+
+<img src="ephemeral-instance-creation.png" alt="Creating an Ephemeral Instance" title="Creating an Ephemeral Instance" width="800" />
+
+You will be able to specify the name of the new Epheemeral Instance. Click on **Create Instance** to create the new Ephemeral Instance.
+
+### Interact with the Ephemeral Instance
+
+After the Epheemeral Instance is created, you will be able to see the instance in the **LocalStack Instance Management** page.
+
+<img src="localstack-ephemeral-instance.png" alt="LocalStack Ephemeral Instance" title="LocalStack Ephemeral Instance" width="800" />
+
+You will also be able to access the following with your Ephemeral Instance:
+
+- Status Page
+- Resource Browser
+- State Management
+- Extensions
+
+<img src="localstack-ephemeral-instance-resource-browser.png" alt="LocalStack Ephemeral Instance Resource Browser" title="LocalStack Ephemeral Instance Resource Browser" width="800" />
+
+### Access the Ephemeral Instance via AWS CLI
+
+You can access the Ephemeral Instance via the AWS CLI by configuring the AWS CLI with the endpoint URL of the Ephemeral Instance. You can find the endpoint URL of the Ephemeral Instance in the **LocalStack Instance Management** page.
+
+To create an S3 bucket in the Ephemeral Instance, run the following command:
+
+{{< command >}}
+$ aws --endpoint-url=<EPHEMERAL_INSTANCE_ENDPOINT_URL> s3 mb s3://<BUCKET_NAME>
+{{< /command >}}
+
+You can replace `<EPHEMERAL_INSTANCE_ENDPOINT_URL>` with the endpoint URL of the Ephemeral Instance and `<BUCKET_NAME>` with the name of the S3 bucket you want to create. To query the list of S3 buckets in the Ephemeral Instance, run the following command:
+
+{{< command >}}
+$ aws --endpoint-url=<EPHEMERAL_INSTANCE_ENDPOINT_URL> s3 ls
+{{< /command >}}
+
+You can further use integrations, such as [CDK](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/), [SAM CLI](https://docs.localstack.cloud/user-guide/integrations/aws-sam/), and [Terraform](https://docs.localstack.cloud/user-guide/integrations/terraform/), to interact with the Ephemeral Instance. In these integrations, you can change the `LOCALSTACK_HOSTNAME` environment variable to the endpoint URL of the Ephemeral Instance.
+
+### Remove the Ephemeral Instance
+
+You can delete the Ephemeral Instance by clicking on the **Remove** button in the **LocalStack Instance Management** page. These instances are automatically terminated after 90 minutes, in case you don`t remove them manually.
+
+## Load Cloud Pod into an Ephmeral Instance
+
+You can load a Cloud Pod into an Ephemeral Instance to seed your pre-existing cloud resources into a freshly created Ephemeral Instance. You can further use AWS CLI or other integrations to interact with these resources, along with using other features of the LocalStack Web Application.
+
+To load a pre-defined Cloud Pod, navigate to the **Cloud Pods Details** for the specific Cloud Pod and click on the **Browse Version** button. Clicking on the button will open a modal where you will be asked to confirm that this will start a new LocalStack instance and load the selected Cloud Pod version.
+
+<img src="cloud-pod-details-page.png" alt="Cloud Pod Details page" title="Cloud Pod Details page" width="800" />
+<br><br>
+
+Click **Continue** to start the Ephemeral Instance and load the Cloud Pod. You will be able to see the Ephemeral Instance on the sidebar. You can copy the endpoint URL of the Ephemeral Instance and use it to manage your cloud resources.