docs: add instructions for creating GitHub App + NuxtHub

resolves #15

Author: danielroe

README.md

@@ -30,6 +30,81 @@ pnpm dev --ui-only
 
 This will fire up a dev server but use the remote API to populate it.
 
+## 🚧 Development environment
+
+Setting up a full development environment takes a little extra effort because `unsight.dev` is implemented as a GitHub App. Here's how to set things up.
+
+### Setup
+
+```sh
+corepack enable
+pnpm i
+```
+
+### Start a local tunnel
+
+```sh
+npx ngrok http 3000
+```
+
+Note the URL under `Forwarding`. It should look something like `https://<GUID>.ngrok-free.app/`. We'll use this in the next step.
+
+### Create a GitHub App for development
+
+1. Navigate to the [GitHub Apps Settings panel](https://github.com/settings/apps) and click 'New GitHub App'.
+
+1. Fill out the form, not changing any defaults:
+
+  - **GitHub App name**: Pick any name at all. I normally add `[dev]` at the end of any apps I'm using in development only.
+  - **Homepage URL**: Doesn't matter; just pick a URL: `https://unsight.dev` would be fine.
+  - **Setup URL**: `http://localhost:3000`. Tick the 'Redirect on update' checkbox underneath.
+  - **Webhook URL**: Put the URL you got when starting ngrok, plus `/github/webhook`: `https://<GUID>.ngrok-free.app/github/webhook`. For the 'Secret' field underneath the URL, create a random GUID or password and make a note of it. 
+  - **Repository permissions**: Select 'Issues': 'Read-only'.
+  - **Subscribe to events**: Select 'Installation target', 'Issues', 'Meta' and 'Repository'.
+
+1. Note down the `App ID:` in your GitHub App settings.
+
+1. Note the 'slug' of your GitHub App. You should be at a URL that looks something like this `https://github.com/settings/apps/unsight-dev`. This last piece (`unsight-dev`) is your app slug.
+
+1. Scroll down to the bottom of the GitHub App setings and click 'Generate a private key'. It should download. Unfortunately this private key is in PKCS#1 format, but we need PKCS#8 in a Cloudflare environment. Run the following command:
+
+```sh
+openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in <path to the downloaded file>.pem -out <path to your repo>-unsight-pkcs8.key
+```
+
+(This outputs a private key file you'll use in the next step.)
+
+### Configure your secrets
+
+Create a `.env` file with the following content (the private key was generated in the last step and can be multi-line, just add a quote before and after it):
+
+```ini
+NUXT_WEBHOOK_GITHUB_SECRET_KEY=<random GUID or password you put in the Webhook Secret field when creating your GitHub App>
+NUXT_PUBLIC_GITHUB_APP_SLUG=<your app slug you saw in the URL of your GitHub App settings>
+NUXT_GITHUB_APP_ID=<GitHub App ID you saw in your GitHub App settings>
+NUXT_GITHUB_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
+MIIEvcIBADAEBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoABADDbja1oaWVufjdT
+...
++qWpvAnlgrGQqvbsuY+XuRnt
+-----END PRIVATE KEY-----"
+```
+
+### Link your Cloudflare account
+
+We use Workers AI and to do that locally we'll need to hook up to Cloudflare. This project uses [NuxtHub](https://hub.nuxt.com/) to do that. You can get going by creating a free NuxtHub account at https://admin.hub.nuxt.com.
+
+Then run this command in your app directory:
+
+```sh
+npx nuxthub link
+```
+
+You can select 'Create a new project'. Any storage region should be fine. Your Nuxt dev server should restart, and you'll see a new `NUXT_HUB_PROJECT_KEY` variable in your `.env` file.
+
+You can now visit http://localhost:3000 and click 'Install as a GitHub app'.
+
+You can now directly visit `http://localhost:3000/<your-user-name>/<your-repo>` to view your clusters.
+
 ## License
 
 Made with ❤️