> ## Documentation Index
> Fetch the complete documentation index at: https://docs-terra.withunify.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Canonical setup guide for new Terra engineers

# 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)

```bash theme={null}
# 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)

Terra scripts are designed to run with Doppler-managed secrets.

```bash theme={null}
# 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.

## Useful CLI Tools (Optional but Recommended)

### Supabase CLI

Useful for local DB operations, policy checks, and migration work.

```bash theme={null}
brew install supabase/tap/supabase
supabase --version
```

### Vercel CLI

Useful for debugging deployment behavior and environment issues.

```bash theme={null}
pnpm dlx vercel --version
```

## Daily Commands

```bash theme={null}
# 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.

***

<CardGroup cols={2}>
  <Card title="Contributing" icon="git-branch" href="/operations/contributing">
    PR workflow and expectations
  </Card>

  <Card title="Testing" icon="flask" href="/operations/testing">
    Test commands and quality gates
  </Card>
</CardGroup>