diff --git a/README.md b/README.md index 8a13cd3..d104a45 100644 --- a/README.md +++ b/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://.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://.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 .pem -out -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= +NUXT_PUBLIC_GITHUB_APP_SLUG= +NUXT_GITHUB_APP_ID= +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//` to view your clusters. + ## License Made with ❤️