Skip to main content

​
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

Terra scripts are designed to run with Doppler-managed secrets. 
# Optional: confirm CLI auth
doppler setup

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

​
Local .env fallback

Use only when Doppler is unavailable.
  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.

​
Supabase CLI

Useful for local DB operations, policy checks, and migration work. 
brew install supabase/tap/supabase
supabase --version

​
Vercel CLI

Useful for debugging deployment behavior and environment issues. 
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

Terra SQL migrations live in apps/terra/migrations/. When adding a migration:
  1. Create the next sequential migration file.
  2. Run verification/tests locally.
  3. Include rollback notes in your PR/release context.

Contributing

PR workflow and expectations

Testing

Test commands and quality gates