Getting started

Start the platform

Install dependencies

pnpm install

Copy each app and package's .env.example to its own .env, then provide the required authentication and email credentials. Keep the encryption keys identical across the API and workers that use them.

for example in apps/*/.env.example packages/*/.env.example docker/.env.example; do
  cp "$example" "${example%.example}"
done

Start PostgreSQL and Redis

pnpm db:up
pnpm queue:up
pnpm db:migrate

Start all applications

pnpm dev

The web application runs at http://localhost:3001, the API at http://localhost:3000, and this documentation site at http://localhost:3002.

Run only the docs

pnpm exec turbo dev --filter=@linea/docs

Configure the docs assistant

The right-side Ask Linea Docs sheet uses the first configured AI provider key. Set DOCS_AI_MODEL to choose a specific registered model:

DOCS_AI_MODEL="gpt-5-mini"
OPENAI_API_KEY="your-key"

Provider credentials are read only by the server-side route. Questions are grounded through a searchDocs tool, and answers link back to its sources.

The assistant requires shared Upstash Redis budget storage in every environment:

UPSTASH_REDIS_REST_URL="your-redis-url"
UPSTASH_REDIS_REST_TOKEN="your-redis-token"
DOCS_AI_DAILY_REQUEST_LIMIT="1000"

Each admitted question reserves one request, without refunds, against the global UTC daily allowance (default 1,000; maximum 100,000). Each client gets at most 10 questions per minute and 50 per UTC day. IPv6 clients share a /64 bucket. Budget storage is bounded by the daily allowance and expires at UTC midnight. Missing or unavailable storage returns 503 within two seconds; exhausted budgets return 429. Deploy all instances with the same Redis database and global allowance.

In production, Vercel's platform client header is trusted. Elsewhere, explicitly set DOCS_ASSISTANT_TRUST_PROXY=1 only behind a reverse proxy that strips incoming X-Forwarded-For and supplies the connection IP as the last entry. Forwarded headers are ignored by default outside Vercel, and missing trusted identity returns 503. Browser requests must be same-origin JSON. Local development uses a shared local client bucket when no trusted proxy is configured.

Requests accept only bounded text history (48 KB body, 11 alternating messages, 500 characters per question, 6,000 per assistant turn, 512 per documentation path). The server allows at most two model steps, 900 output tokens per step, one documentation search, no provider retries, and 30 seconds of generation. Provider account monthly spend caps and deployment WAF rules remain separate operator configuration; the application does not configure them.

For production semantic search, create an Upstash Vector index with a hosted embedding model and set its REST credentials:

UPSTASH_VECTOR_REST_URL="your-index-url"
UPSTASH_VECTOR_REST_TOKEN="your-index-token"

Ingest the MDX documentation after configuring those variables:

pnpm --filter @linea/docs ingest

The command writes to a new namespace and prints the DOCS_VECTOR_NAMESPACE value to deploy. This keeps the active index intact if ingestion fails. Without Upstash credentials, local development uses the built-in documentation search.

Verify a change

Run the same checks used by CI before opening a pull request:

pnpm lint
pnpm typecheck
pnpm format:check

For a first code change, use the repository map to find the owner, then follow the contribution guide for tests, contracts, and pull-request expectations.

See the contribution guide for repository conventions and the documentation workflow.

Prerequisites