Skip to content

SETUP.md

Latest commit

 

History

History
67 lines (49 loc) · 2.5 KB

SETUP.md

File metadata and controls

67 lines (49 loc) · 2.5 KB
Raw

Local setup

This guide runs BRAIN on your machine against the bundled sample vault. Once it works, swap in your own vault per vault.md.

Prerequisites

  • Docker + Docker Compose (v2.24+)
  • Node 20+ (only needed if running web outside Docker; the dev flow uses Docker)
  • Python 3.12+ and uv (optional — only for running the api outside Docker)
  • A GitHub OAuth app with callback http://localhost:3000/api/auth/callback/github
  • A Voyage AI API key (free tier is enough for the sample vault)
  • An OpenRouter API key

Steps

# 1. Clone and enter the repo.
git clone <your-fork-url> brain && cd brain

# 2. Copy the env template and fill it in.
cp .env.example .env
$EDITOR .env

# Minimum required values for local dev:
#   NEXTAUTH_SECRET       openssl rand -base64 32
#   GITHUB_CLIENT_ID
#   GITHUB_CLIENT_SECRET
#   ALLOWED_GITHUB_USER   your GitHub login
#   INTERNAL_API_SECRET   openssl rand -base64 32
#   VOYAGE_API_KEY
#   OPENROUTER_API_KEY
#   ADMIN_REINDEX_TOKEN   openssl rand -base64 32
# Leave DOMAIN, NEXT_PUBLIC_DOMAIN, CF_API_TOKEN, ACME_EMAIL, TS_AUTHKEY blank.

# 3. Point at the bundled sample vault (or your own).
export VAULT_PATH="$(pwd)/vault.example"

# 4. Bring up the stack.
./scripts/dev.sh

# 5. Seed embeddings (first run only; takes ~30s on the sample vault).
./scripts/seed-embed.sh

# 6. Open the app.
open http://localhost:3000

Sign in with GitHub. The username on your token must match ALLOWED_GITHUB_USER.

Helper scripts

  • scripts/dev.sh — docker compose up with the dev override (hot-reload, vault bind-mount, no Caddy).
  • scripts/seed-embed.sh — POST /admin/reindex with ADMIN_REINDEX_TOKEN to (re)build the vector store.
  • scripts/new-secret.sh — random base64 secrets.

Troubleshooting

  • Sign-in loops back to GitHub. Your GitHub login is not in ALLOWED_GITHUB_USER, or the OAuth callback URL doesn't match.
  • Empty results in chat / graph. Run ./scripts/seed-embed.sh to populate ChromaDB; verify api logs for embedding errors.
  • 429 from Voyage. The free tier rate-limits aggressively. The embedder retries with backoff; let it finish.
  • web healthcheck failing. First boot can take ~60s. Watch docker compose logs -f web.

What's next