​

Local Development

This is the canonical “Setting Up Terra” guide. If onboarding notes conflict with this page, use this page.

​

Who This Is For

• New engineers joining Terra development
• Existing engineers setting up a new laptop
• Engineers troubleshooting local environment drift

​

Prerequisites

• macOS or Linux shell access
• Node.js 20+
• pnpm 9+
• Access to Terra GitHub repo (scholarfund/terra)
• Doppler access for the unify-platform project

​

Fast Setup (macOS)

# 1) Xcode CLT (needed for some native packages)
xcode-select --install

# 2) nvm + Node 20+
brew install nvm
nvm install node
nvm use node

# 3) pnpm
brew install pnpm

# 4) Doppler CLI
brew install dopplerhq/cli/doppler
doppler login

# 5) Clone and install
git clone https://github.com/scholarfund/terra.git
cd terra
pnpm install

# 6) Run Terra
pnpm --dir apps/terra dev

​

Environment Setup

​

Doppler (recommended)

# Optional: confirm CLI auth
doppler setup

# Start Terra dev server (uses Doppler in script)
pnpm --dir apps/terra dev

​

Local .env fallback

1. Copy apps/terra/.env.example to apps/terra/.env.local.
2. Populate required values (Supabase, WorkOS, encryption key, integrations).
3. Run with local env.

​

Useful CLI Tools (Optional but Recommended)

​

Supabase CLI

brew install supabase/tap/supabase
supabase --version

​

Vercel CLI

pnpm dlx vercel --version

​

Daily Commands

# Unit/integration tests
pnpm --dir apps/terra test

# E2E tests
pnpm --dir apps/terra test:e2e

# Typecheck
pnpm --dir apps/terra tsc --noEmit

# Load certification gate
pnpm --dir apps/terra test:load

# Lint
pnpm --dir apps/terra lint

​

Quick Verification Checklist

• pnpm --dir apps/terra dev starts without missing-env crashes
• pnpm --dir apps/terra test runs locally
• pnpm --dir apps/terra tsc --noEmit passes
• You can open /status locally and get HTTP 200

​

Migrations

1. Create the next sequential migration file.
2. Run verification/tests locally.
3. Include rollback notes in your PR/release context.