API Reference

Variáveis de Ambiente (Produção)

Lista completa das variáveis de ambiente necessárias em produção para cada serviço do monorepo. Use como checklist antes de subir o ambiente.

As variáveis NEXT_PUBLIC_* do apps/web são embutidas em build pelo Next.js. Se você muda em runtime, o valor antigo continua no bundle. Garanta que estão corretas no args do docker-compose.yml (ou nas envs do provedor de build) antes do build.

apps/web (Next.js)

Container principal. Serve o frontend e a API REST.

Banco e Auth

Variável	Tipo	Obrigatório	Descrição
`DATABASE_URL`	runtime	sim	PostgreSQL (ex: `postgresql://user:password@host:5432/refstash`)
`BETTER_AUTH_SECRET`	runtime	sim	Chave de sessão. Gere com `openssl rand -base64 32`
`BETTER_AUTH_URL`	runtime	sim	URL pública do app (ex: `https://organization.kodea.com.br`)
`NEXT_PUBLIC_APP_URL`	build	sim	Mesma URL — usada em e-mails de convite. Injetada em build
`CLOUDFLARE_URL`	runtime	se usar Cloudflare Access	Domínio protegido pela Cloudflare

Storage (S3 / R2)

Variável	Tipo	Obrigatório	Descrição
`STORAGE_ENDPOINT`	runtime	sim	Endpoint S3-compatible (R2, MinIO, etc.)
`STORAGE_BUCKET`	runtime	sim	Nome do bucket de uploads (avatar, logo, anexos)
`STORAGE_ACCESS_KEY`	runtime	sim	Access key S3
`STORAGE_SECRET_KEY`	runtime	sim	Secret key S3
`STORAGE_REGION`	runtime	sim	Região (default: `us-east-1`)

Colaboração (notas — Tiptap + Hocuspocus)

Variável	Tipo	Obrigatório	Descrição
`NEXT_PUBLIC_COLLAB_WS_URL`	build	sim	`wss://collab.seudominio.com` — URL do serviço Hocuspocus. Injetada em build
`COLLAB_JWT_SECRET`	runtime	sim	Secret para assinar JWTs de sessão. Deve ser o mesmo em `apps/collab` e `apps/tldraw-sync`

Boards (tldraw — Cloudflare Worker)

Variável	Tipo	Obrigatório	Descrição
`NEXT_PUBLIC_TLDRAW_SYNC_WS_URL`	build	sim	`wss://locus-tldraw-sync.seudominio.com` — URL do Worker. Injetada em build
`NEXT_PUBLIC_TLDRAW_LICENSE_KEY`	build	sim	Chave de licença tldraw (validação server-side)

E-mail (Resend)

Variável	Tipo	Obrigatório	Descrição
`RESEND_API_KEY`	runtime	sim (se envia e-mail)	API key do Resend
`RESEND_FROM_EMAIL`	runtime	sim (se envia e-mail)	Remetente verificado (ex: `Locus <[email protected]>`)

IA

Pelo menos uma das chaves é obrigatória. As URLs base são opcionais (úteis para proxies).

Variável	Tipo	Obrigatório	Descrição
`ANTHROPIC_API_KEY`	runtime	ao menos 1	Chave Anthropic (Claude)
`ANTHROPIC_BASE_URL`	runtime	não	Proxy / gateway alternativo
`MINIMAX_API_KEY`	runtime	ao menos 1	Chave MiniMax M2
`MINIMAX_BASE_URL`	runtime	não	Proxy / gateway alternativo

Opcionais

Variável	Tipo	Descrição
`NEXT_PUBLIC_API_URL`	build	Base da API consumida pelo cliente (default = próprio host). Injetada em build
`NEXT_PUBLIC_TIPTAP_COLLAB_DOC_PREFIX`	build	Prefixo de doc do Tiptap Cloud (legado)
`NEXT_PUBLIC_TIPTAP_COLLAB_APP_ID`	build	App ID do Tiptap Cloud (legado)
`NEXT_PUBLIC_TIPTAP_COLLAB_TOKEN`	build	Token do Tiptap Cloud (legado)
`NEXT_PUBLIC_TIPTAP_AI_APP_ID`	build	App ID do Tiptap AI
`NEXT_PUBLIC_TIPTAP_AI_TOKEN`	build	Token do Tiptap AI
`NEXT_PUBLIC_USE_JWT_TOKEN_API_ENDPOINT`	build	Flag de uso de endpoint JWT do Tiptap

apps/collab (Hocuspocus — servidor de colaboração de notas)

Variável	Obrigatório	Descrição
`DATABASE_URL`	sim	Mesma do `apps/web`
`COLLAB_JWT_SECRET`	sim	Mesmo valor do `apps/web` e do `apps/tldraw-sync`
`PORT`	não	Porta do servidor (default `1234`)

apps/tldraw-sync (Cloudflare Worker)

Este serviço não usa .env — as configs vão no wrangler.toml e os secrets são setados via CLI.

1. Variáveis no `wrangler.toml` (já configurado)

[vars]
ALLOWED_ORIGIN = "https://seudominio.com"  # editar para seu domínio

2. Bindings (já configurados no `wrangler.toml`)

TLDRAW_DURABLE_OBJECT — namespace do Durable Object TldrawDurableObject
UPLOADS — R2 bucket locus-tldraw-assets (criar antes do primeiro deploy)

3. Secrets (setar com `wrangler`)

cd apps/tldraw-sync

# Mesmo COLLAB_JWT_SECRET do apps/web e apps/collab
pnpm exec wrangler secret put COLLAB_JWT_SECRET

Checklist de deploy

# 1. Criar o bucket R2 (só na primeira vez)
pnpm exec wrangler r2 bucket create locus-tldraw-assets

# 2. Setar o secret compartilhado
pnpm exec wrangler secret put COLLAB_JWT_SECRET

# 3. Atualizar ALLOWED_ORIGIN no wrangler.toml para o domínio real

# 4. Deploy
pnpm exec wrangler deploy

A URL gerada (*.workers.dev ou domínio customizado) deve ser colocada em NEXT_PUBLIC_TLDRAW_SYNC_WS_URL no apps/web antes do próximo build (lembre: é build-time).

Resumo: secrets compartilhados

Três serviços precisam compartilhar o COLLAB_JWT_SECRET (HS256). Gere uma única vez e replique:

openssl rand -base64 32

Serviço	Como setar
`apps/web`	env de runtime do container
`apps/collab`	env de runtime do container
`apps/tldraw-sync`	`wrangler secret put COLLAB_JWT_SECRET`

Getting Started Motivos