From a689cdfd77f877fa8a94c1a6e17d7a7b8c051b9f Mon Sep 17 00:00:00 2001 From: Srivatsan Srinivasan Date: Thu, 4 Dec 2025 22:49:16 +0530 Subject: [PATCH 1/3] docs: Update README and add DEV_ENV_SETUP for detailed instructions to help understand env variables for local dev --- README.md | 3 +- docs/DEV_ENV_SETUP.md | 167 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+), 1 deletion(-) create mode 100644 docs/DEV_ENV_SETUP.md diff --git a/README.md b/README.md index 561c759..148fe2f 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,8 @@ A monorepo containing a Next.js web app and Cloudflare Workers backend. Check it cp packages/db/.env.example packages/db/.env ``` - Fill in the values in each `.env` file. + - Fill in the values in each `.env` file. + - See [DEV_ENV_SETUP](./docs/DEV_ENV_SETUP.md) for detailed instructions and explanations for each variable. 3. **Set up the database** diff --git a/docs/DEV_ENV_SETUP.md b/docs/DEV_ENV_SETUP.md new file mode 100644 index 0000000..fb4f0f0 --- /dev/null +++ b/docs/DEV_ENV_SETUP.md @@ -0,0 +1,167 @@ +# Environment Variables Setup Guide + +This guide explains how to configure all environment variables for local development. + +--- + +# packages/db/.env + +Database configuration for the Drizzle ORM layer. + +#### `DATABASE_URL` • Required +PostgreSQL/Any SQL Connection connection string for your local database. + +**Setup:** +1. Start PostgreSQL +2. Create database: `psql postgres -c "CREATE DATABASE clankerrank;"` +3. Set value: `postgresql://localhost:5432/clankerrank` + +--- + +# apps/backend/.env + +Backend API configuration for the Cloudflare Workers service. + +#### `AI_GATEWAY_API_KEY` • Required +API key for accessing AI models through Vercel AI Gateway. +- Sign up at [Vercel](https://vercel.com/) +- Navigate to your project → AI → Create Gateway +- Copy the API key from the dashboard + +#### `DATABASE_URL` • Required +PostgreSQL connection string (same as `packages/db/.env`) +- Value: `postgresql://localhost:5432/clankerrank` + +#### `PROJECT_NAME` • Optional +Display name for your project +- Default: `Clankerrank` + +#### `WORKOS_API_KEY` • Required +WorkOS AuthKit API key for authentication and user management +- Sign up at [WorkOS](https://workos.com/) +- Create a new project with AuthKit enabled +- Navigate to API Keys tab → copy Secret Key (starts with `sk_test_`) + +#### `WORKOS_CLIENT_ID` • Required +WorkOS AuthKit Client ID for your application +- Find in WorkOS dashboard → API Keys tab → copy Client ID (starts with `client_`) + +#### `WORKOS_COOKIE_PASSWORD` • Required +Secret key used by AuthKit to encrypt session cookies (must be at least 32 characters) +- Generate: `openssl rand -base64 32` +- Keep secure - changing this invalidates all existing sessions + +#### `NEXT_PUBLIC_WORKOS_REDIRECT_URI` • Required (pre-configured) +OAuth callback URL for WorkOS AuthKit authentication +- Local dev value: `http://localhost:3000/callback` +- In WorkOS dashboard → Redirects tab → add `http://localhost:3000/callback` as sign-in callback +- Also set app homepage URL to `http://localhost:3000` + +#### `POSTHOG_API_KEY` • Optional +PostHog API key for product analytics +- Sign up at [PostHog](https://posthog.com/) → copy Project API Key +- App functions normally if not provided + +--- + +# `apps/web/.env` + +Frontend web application configuration (Next.js). + +#### `AI_GATEWAY_API_KEY` • Required +Same as backend - API key for Vercel AI Gateway access +- Value: Same as `apps/backend/.env` + +#### `DATABASE_URL` • Required +PostgreSQL connection string for server-side database access +- Value: `postgresql://localhost:5432/clankerrank` + +#### `PROJECT_NAME` • Optional +Display name for your project +- Default: `Clankerrank` + +#### `NEXT_PUBLIC_BACKEND_URL` • Required (pre-configured) +URL where the backend API is running +- Local dev value: `http://localhost:8787` +- Production: Update to your deployed backend URL + +#### `NEXT_PUBLIC_BACKEND_API_KEY` • Optional (leave empty) +Default encrypted user ID for API authentication (fallback value) +- Local dev: Leave empty (`NEXT_PUBLIC_BACKEND_API_KEY=`) +- Why it's optional: Users authenticate via WorkOS before making API calls, their encrypted user ID is dynamically generated +- Advanced: See [Generating a Test API Key](#generating-a-test-api-key-advanced) section below if needed + +#### `WORKOS_API_KEY` • Required +Same as backend - WorkOS AuthKit API key +- Value: Same as `apps/backend/.env` + +#### `WORKOS_CLIENT_ID` • Required +Same as backend - WorkOS AuthKit Client ID +- Value: Same as `apps/backend/.env` + +#### `WORKOS_COOKIE_PASSWORD` • Required +Same as backend - AuthKit session cookie encryption secret +- Value: Same as `apps/backend/.env` (must match exactly) + +#### `NEXT_PUBLIC_WORKOS_REDIRECT_URI` • Required (pre-configured) +OAuth callback URL for WorkOS authentication +- Value: `http://localhost:3000/callback` + +--- + +# Generating a Test API Key (Advanced) + +If you need to test API calls without going through WorkOS authentication, you can generate an encrypted API key: + +1. First, create a test user in WorkOS and get their user ID (format: `user_01XXXXX`) + +2. Create a script to encrypt the user ID: + +```typescript +// scripts/generate-test-api-key.ts +import { createCipheriv, randomBytes, pbkdf2Sync } from "crypto"; + +const ALGORITHM = "aes-256-gcm"; +const KEY_LENGTH = 32; +const IV_LENGTH = 16; +const SALT_LENGTH = 16; +const ITERATIONS = 100000; + +function deriveKey(password: string, salt: Buffer): Buffer { + return pbkdf2Sync(password, salt, ITERATIONS, KEY_LENGTH, "sha256"); +} + +function encryptUserId(userId: string, password: string): string { + const salt = randomBytes(SALT_LENGTH); + const iv = randomBytes(IV_LENGTH); + const key = deriveKey(password, salt); + const cipher = createCipheriv(ALGORITHM, key, iv); + + let encrypted = cipher.update(userId, "utf8"); + encrypted = Buffer.concat([encrypted, cipher.final()]); + + const tag = cipher.getAuthTag(); + const combined = Buffer.concat([salt, iv, encrypted, tag]); + + return combined.toString("base64"); +} + +const userId = process.argv[2]; +const password = process.env.WORKOS_COOKIE_PASSWORD; + +if (!userId || !password) { + console.error("Usage: WORKOS_COOKIE_PASSWORD=xxx tsx scripts/generate-test-api-key.ts user_01ABC123"); + process.exit(1); +} + +console.log("Encrypted API Key:", encryptUserId(userId, password)); +``` + +3. Run it: +```sh +WORKOS_COOKIE_PASSWORD=your_cookie_password tsx scripts/generate-test-api-key.ts user_01ABC123 +``` + +4. Add the output to `NEXT_PUBLIC_BACKEND_API_KEY` in `apps/web/.env` + +**Note:** This is rarely needed for local development since you can just log in normally. \ No newline at end of file From 4806452b31ab6271492c7a63e53b588817ea477e Mon Sep 17 00:00:00 2001 From: Srivatsan Srinivasan Date: Thu, 4 Dec 2025 22:56:38 +0530 Subject: [PATCH 2/3] remove: redundant use of the word Connection lol --- docs/DEV_ENV_SETUP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DEV_ENV_SETUP.md b/docs/DEV_ENV_SETUP.md index fb4f0f0..e304a9f 100644 --- a/docs/DEV_ENV_SETUP.md +++ b/docs/DEV_ENV_SETUP.md @@ -9,7 +9,7 @@ This guide explains how to configure all environment variables for local develop Database configuration for the Drizzle ORM layer. #### `DATABASE_URL` • Required -PostgreSQL/Any SQL Connection connection string for your local database. +PostgreSQL/Any SQL connection string for your local database. **Setup:** 1. Start PostgreSQL From 1a658527c16a166464fa80f22c9dd341cf75cef9 Mon Sep 17 00:00:00 2001 From: Srivatsan Srinivasan <100481554+srivatsan0611@users.noreply.github.com> Date: Fri, 5 Dec 2025 15:19:14 +0530 Subject: [PATCH 3/3] Update env connection details to clankerloop --- docs/DEV_ENV_SETUP.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/DEV_ENV_SETUP.md b/docs/DEV_ENV_SETUP.md index e304a9f..d100d16 100644 --- a/docs/DEV_ENV_SETUP.md +++ b/docs/DEV_ENV_SETUP.md @@ -13,8 +13,8 @@ PostgreSQL/Any SQL connection string for your local database. **Setup:** 1. Start PostgreSQL -2. Create database: `psql postgres -c "CREATE DATABASE clankerrank;"` -3. Set value: `postgresql://localhost:5432/clankerrank` +2. Create database: `psql postgres -c "CREATE DATABASE clankerloop;"` +3. Set value: `postgresql://localhost:5432/clankerloop` --- @@ -30,11 +30,11 @@ API key for accessing AI models through Vercel AI Gateway. #### `DATABASE_URL` • Required PostgreSQL connection string (same as `packages/db/.env`) -- Value: `postgresql://localhost:5432/clankerrank` +- Value: `postgresql://localhost:5432/clankerloop` #### `PROJECT_NAME` • Optional Display name for your project -- Default: `Clankerrank` +- Default: `Clankerloop` #### `WORKOS_API_KEY` • Required WorkOS AuthKit API key for authentication and user management @@ -74,11 +74,11 @@ Same as backend - API key for Vercel AI Gateway access #### `DATABASE_URL` • Required PostgreSQL connection string for server-side database access -- Value: `postgresql://localhost:5432/clankerrank` +- Value: `postgresql://localhost:5432/clankerloop` #### `PROJECT_NAME` • Optional Display name for your project -- Default: `Clankerrank` +- Default: `clankerloop` #### `NEXT_PUBLIC_BACKEND_URL` • Required (pre-configured) URL where the backend API is running @@ -164,4 +164,4 @@ WORKOS_COOKIE_PASSWORD=your_cookie_password tsx scripts/generate-test-api-key.ts 4. Add the output to `NEXT_PUBLIC_BACKEND_API_KEY` in `apps/web/.env` -**Note:** This is rarely needed for local development since you can just log in normally. \ No newline at end of file +**Note:** This is rarely needed for local development since you can just log in normally.