Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/stagehand-framework/stagehand

Stagehand is an open-source drop-in solution for deploying and managing review apps for frontends
https://github.com/stagehand-framework/stagehand

aws cli github-actions service-worker staging-environment

Last synced: 9 months ago
JSON representation

Stagehand is an open-source drop-in solution for deploying and managing review apps for frontends

Awesome Lists containing this project

README 

          


  




Stagehand: Automated review apps for modern frontend applications


All you need is an AWS account and a GitHub repo to get started



Stagehand is a drop-in solution that provides review apps for modern

frontend applications. We are a framework that automatically manages

review apps for your application’s GitHub repository on your own cloud

infrastructure. We use AWS, GitHub Actions, and some Stagehand

client-side code to set-up, deploy, manage, and teardown review apps

for your frontend application.



To learn more, please read our [case study](http://stagehand-framework.github.io) or feel free to drop us a line!



# Prerequisites



- AWS Account

- AWS CLI configured to your AWS Account

  - For help, see this article: https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html

- GitHub Token

  - Log into your GitHub Account

  - Settings => Developer Settings => Personal Access Tokens => Generate new Token => Only provide access to Repositories

- Node

- NPM

- Repository for static front-end application (ie Gatsby, Hugo, NextJS, React)



# Installation



- Run the install command: `npm i -g stagehand-framework`



# Your First Stagehand Application



- Navigate to the root of your local git repository, make sure that it is connected with a GitHub repository

- Run `stagehand init`

- Provide your GitHub Token (this token only needs to be provided the very first use)

- A folder in your home directory `/ .stagehand` will be created to house your configuration and your application data for Stagehand



### Setting Up your Github Actions



- You will be prompted to provide:

  - The name you wish to use

  - The setup command your app uses (ie npm install, brew install hugo)

  - The build command your app uses (ie npm run-script build, hugo)

  - The directory that your app builds to (ie public, out, build)

- This will create a `.github/workflow` directory in your repo for GitHub Actions.

  - If you need to alter your GitHub build process look for `create_review_app.yml` and `remove_review_app.yml`



### Adding build time environment variables



- First add each build time environment variables to your GitHub repository secrets

  - Settings => Secrets

- Next you must access each of those secrets in your build file

- If you navigate to `.github/workflows/create_review_app` you will come across this code on line 35



```

####### Uncomment below to add env variables to use during build process #######

####### Add \n to the end of each secret to start a new line #######

####### EXCEPT DO NOT add to the end of the last secret #######

      # - name: create .env

      #   run: echo -e "\

      #     SECRET1=${{ secrets.YOUR_SECRET1 }}\n

      #     SECRET2=${{ secrets.YOUR_SECRET2 }}" > .env

```



- If you uncomment the last 4 lines you can add in your own secrets there to provide to a `.env` file at build time.



##### _Some Examples:_



One secret named `API_KEY` and want to use a `.env.development` file:



```

- name: create .env

  run: echo -e "\

    API_KEY=${{ secrets.API_KEY }}" > .env.development

```



An `API_KEY` and a `DB_PASSWORD` secret for a `.env` file:



```

- name: create .env

  run: echo -e "\

    DB_PASSWORD=${{ secrets.DB_PASSWORD }}\n

    API_KEY=${{ secrets.API_KEY }}" > .env

```



An `API_KEY`, `DB_PASSWORD`, and `API_URL` secrets for a `.env.staging` file



```

- name: create .env

  run: echo -e "\

    DB_PASSWORD=${{ secrets.DB_PASSWORD }}\n

    API_URL=${{ secrets.API_URL }}\n

    API_KEY=${{ secrets.API_KEY }}" > .env.staging

```



### Setting Up Your Stagehand Dashboard



- Stagehand needs two additional pieces of information to know how to handle routing:

- If you app is a Single Page Application (ie React)

- Or if you app has all of its static routes served from `path/index.html` as opposed to just `path.html`

  - Gatsby uses this routing out of the box

  - You can check your build folder (public, out, build) to see how your application handles routing

- This will create the `.github/stagehand` folder where the html, javascript, and service worker files will live

- We provide a basic dashboard overlay that will be visible from every page of your stagehand application

  - It is an HTML wrapper around your entire application

  - We provide a banner at the top of your page containing some metadata (Creation Time, branch that the PR was opened on, and owner of the repository)

- If you wish to add to this dashboard you can alter the html and javascript that we provide out of the box.



### Pushing Your `./github` folder to your GitHub Repostory



- The last step is pushing your `./github` folder to your repository

- You are now ready to start using Stagehand



# Workflow



- For every Pull Request you create, Stagehand will build and create a staging environment for you

- Stagehand will also build additional staging environments for every commit or change you make to the existing Pull Request

- You can compare multiple versions of your application to each other

- When the Pull request is closed or merged Stagehand will destroy all the staging environments that existed from that Pull Request



# Stagehand Commands



### `stagehand init`



- Run this command from the root of your repostory that is linked to a GitHub repository

- Follow the prompts to create a new Stagehand application

- See "Your First Stagehand Application" above for more details on this process



### `stagehand list`



- This will show all the Stagehand applications that you currently are involved with

- Once you select a Stagehand application you will be shown a list of current staging environments that exist

- Open them up by selecting and pressing enter.



### `stagehand access`



- Use this command to `VIEW`, `ADD`, or `REMOVE` access to one of your applications

- `ADD` access lets other developers working on the same repository have access to the active staging environments

- To `ADD` access you must have the user's AWS Account Email

- The `ADD` command will return the name of the storage location of the staging environments



### `stagehand add`



- First you provide a user access to your Stagehand application using `stagehand access` => `ADD`

- The user you provided access to must input the name of the storage location provided from the previous command

- This will give you access to the application when you run `stagehand list`



### `stagehand destroy`



- First you select which Stagehand application you wish to remove

- If you are the owner of the Stagehand application:

  - This command will remove:

    - Stagehand related files and folders from your repository

    - AWS infrastructure

    - Application data from the local datastore

    - AWS Secrets from your GitHub repository

- If you are not the owner of the application (it was added using `stagehand add`):

  - This command will just remove application data from the local datastore