From 223def1a3c690ec073a9e4d3c55c2ebf647be9f8 Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Sat, 1 Aug 2026 17:07:12 +0000 Subject: [PATCH] docs: correct setup ordering and drop stale og image secret --- .env.example | 11 ----------- README.md | 47 ++++++++++++++++++++++++++++++----------------- package.json | 1 - 3 files changed, 30 insertions(+), 29 deletions(-) diff --git a/.env.example b/.env.example index cedfd4f..56b9362 100644 --- a/.env.example +++ b/.env.example @@ -1,16 +1,5 @@ # Copy to `.env` and fill in. -# --------------------------------------------------------------------------- -# OG image URL signing secret. nuxt-og-image renders OG images on demand at -# runtime; this HMAC secret signs the generated URLs so callers can't craft -# arbitrary image-generation requests against the endpoint (which would burn -# CPU and bandwidth). -# -# Generate with: pnpm gen:og-image-secret -# (or any 32-byte hex string) -# --------------------------------------------------------------------------- -NUXT_OG_IMAGE_SECRET=<32-byte hex string> - # --------------------------------------------------------------------------- # Public URL the app is reachable at. For local dev this is the loopback host # (note: 127.0.0.1, not localhost — required by the AT Proto OAuth spec for diff --git a/README.md b/README.md index 509a1b8..081c046 100644 --- a/README.md +++ b/README.md @@ -37,12 +37,16 @@ local origin (`http://127.0.0.1:3000`), Callback URL to `http://127.0.0.1:3000/api/github/oauth/callback`, Setup URL to `http://127.0.0.1:3000/connect`, and enable "Redirect on update". -Keep user OAuth toggles at their defaults unless you specifically need them, but -keep webhooks active and set Webhook URL to your Smee URL with a webhook secret -you choose. +Leave the user authorization toggles at their defaults, but do copy the Client +ID and generate a client secret: the Callback URL above drives a user-OAuth leg +that proves a connecting user administers the installation before any tangled +handle is bound to it, so `NUXT_GITHUB_APP_CLIENT_ID` and +`NUXT_GITHUB_APP_CLIENT_SECRET` are required, not optional. Keep webhooks active +and set Webhook URL to your Smee URL with a webhook secret you choose. Set repository permissions to `contents:read` and `metadata:read`. For event subscriptions, use `push`, `create`, `delete`, and `repository`. + If you do not see those event checkboxes yet, save the app after adding the webhook URL, then return to the "Permissions & events" page and select them there. @@ -50,44 +54,53 @@ there. After creation, copy App ID, Client ID, generate a client secret, and generate a private key (`.pem`) for the `NUXT_GITHUB_APP_*` values. -If you need to install this app in -organizations/accounts other than the owner account, go to Advanced > Danger -zone and make the app public. +If you need to install this app in organizations/accounts other than the owner +account, go to Advanced > Danger zone and make the app public. + +Now install dependencies, which the secret-generation helpers below need: + +```bash +corepack enable +pnpm install +``` -Now create your local env file and fill all variables: +Create your local env file and fill in every variable: ```bash cp .env.example .env ``` -Use these helpers for generated values: +Use these helpers for the generated values: ```bash -pnpm gen:og-image-secret # NUXT_OG_IMAGE_SECRET pnpm gen:jwk # NUXT_ATPROTO_PRIVATE_JWK pnpm gen:encryption-key # NUXT_ENCRYPTION_KEY and NUXT_SESSION_PASSWORD pnpm gen:cron-secret # CRON_SECRET ``` -After `.env` is complete, install dependencies and run migrations: +Once `.env` is complete, apply migrations: ```bash -corepack enable -pnpm install pnpm db:migrate ``` -Local development should run in three terminals: +Local development runs in three terminals. Proxy webhooks to your dev server: ```bash -# terminal 1 smee --url --target http://127.0.0.1:3000/api/github/webhook +``` -# terminal 2 +Run the app: + +```bash pnpm dev +``` + +And drain the job queue as needed while developing (Vercel Cron does this in +production): -# terminal 3 -pnpm jobs:tick # run this to sync queued jobs while developing; Vercel Cron runs it in production +```bash +pnpm jobs:tick ``` ## Deploy to Vercel diff --git a/package.json b/package.json index 103f3a6..6e25989 100644 --- a/package.json +++ b/package.json @@ -20,7 +20,6 @@ "db:generate": "drizzle-kit generate", "db:migrate": "drizzle-kit migrate", "db:studio": "drizzle-kit studio", - "gen:og-image-secret": "node -e \"console.log(require('node:crypto').randomBytes(32).toString('hex'))\"", "gen:jwk": "node scripts/gen-jwk.ts", "gen:encryption-key": "node -e \"console.log(require('node:crypto').randomBytes(32).toString('base64'))\"", "gen:cron-secret": "node -e \"console.log(require('node:crypto').randomBytes(32).toString('base64url'))\"", -- knotmirror 0.0.1