Skip to content

docs: fix local dev setup instructions #584

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jack-piplabs wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: fix local dev setup instructions #584

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 26 additions & 12 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Welcome! ClawHub is the public skill registry for [OpenClaw](https://github.com/
### Prerequisites

- [Bun](https://bun.sh/) (Convex CLI runs via `bunx`, no global install needed)
- [Node.js](https://nodejs.org/) v18, 20, 22, or 24 (required by the local Convex backend; v25+ is not yet supported)

### Install and configure

Expand All @@ -26,7 +27,6 @@ Edit `.env.local` with the following values for **local Convex**:
VITE_CONVEX_URL=http://127.0.0.1:3210
VITE_CONVEX_SITE_URL=http://127.0.0.1:3210
SITE_URL=http://localhost:3000
CONVEX_SITE_URL=http://127.0.0.1:3210

# Deployment used by `bunx convex dev`
CONVEX_DEPLOYMENT=anonymous:anonymous-clawhub
Expand All @@ -37,33 +37,44 @@ CONVEX_DEPLOYMENT=anonymous:anonymous-clawhub
1. Go to [github.com/settings/developers](https://github.com/settings/developers) and create a new OAuth App.
2. Set **Homepage URL** to `http://localhost:3000`.
3. Set **Authorization callback URL** to `http://127.0.0.1:3210/api/auth/callback/github`.
4. Copy the Client ID and generate a Client Secret, then add them to `.env.local`:
4. Copy the Client ID and generate a Client Secret.

### Run the Convex backend

Start the local Convex backend first — other setup steps depend on it:

```bash
bunx convex dev --typecheck=disable
```

### Set backend environment variables

The Convex backend has its own env var store separate from `.env.local`. With the backend running, open a new terminal and set the required variables:

```bash
AUTH_GITHUB_ID=<your-client-id>
AUTH_GITHUB_SECRET=<your-client-secret>
bunx convex env set AUTH_GITHUB_ID <your-client-id>
bunx convex env set AUTH_GITHUB_SECRET <your-client-secret>
bunx convex env set SITE_URL http://localhost:3000
```

### JWT keys (for Convex Auth)

Generate the signing keys:
With the backend still running, generate the signing keys:

```bash
bunx @convex-dev/auth
```

This outputs `JWT_PRIVATE_KEY` and `JWKS` values — paste them into `.env.local`.
This sets `JWT_PRIVATE_KEY` and `JWKS` on the Convex backend and outputs values you can also save to `.env.local` for reference.

### Run the app
### Run the frontend

```bash
# Terminal A: local Convex backend
bunx convex dev

# Terminal B: frontend (port 3000)
bun run dev
bun run dev -- --port 3000
```

Change the port if 3000 is already in use, and update `SITE_URL` in both `.env.local` and the Convex backend (`bunx convex env set SITE_URL ...`) to match.

### Seed the database

Populate sample data so the UI isn't empty:
Expand All @@ -74,6 +85,9 @@ bunx convex run --no-push devSeed:seedNixSkills

# 50 extra skills for pagination testing (optional)
bunx convex run --no-push devSeedExtra:seedExtraSkillsInternal

# Refresh the cached skills count (required after seeding)
bunx convex run --no-push statsMaintenance:updateGlobalStatsInternal
```

To reset and re-seed:
Expand Down