Instalação e configuração

Este guia leva você de um clone vazio até o RoboStage rodando em http://localhost:3000, com banco de dados, autenticação e armazenamento configurados.

Pré-requisitos#

1. Clonar e instalar#

git clone https://github.com/ohthias/roboStage.git
cd roboStage
npm install

2. Variáveis de ambiente#

Crie um arquivo .env.local na raiz do projeto. Ele já está no .gitignore.

Cuidado

Nunca envie .env.local, chaves ou secrets para o Git — nem em issues e pull requests.

# Banco de dados (obrigatória)
DATABASE_URL="postgresql://usuario:senha@host/banco?sslmode=require"
 
# Clerk (obrigatórias)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."
CLERK_WEBHOOK_SECRET="whsec_..."
 
# Cloudflare R2 — arquivos do QuickBrick Studio (opcional em dev)
R2_ACCOUNT_ID=""
R2_ACCESS_KEY_ID=""
R2_SECRET_ACCESS_KEY=""
R2_BUCKET="quickbrick-projects"
 
# NECTA — publicações lidas do Supabase (opcional)
NEWS_SUPABASE_URL=""
NEWS_SUPABASE_ANON_KEY=""
NEWS_REVALIDATE_SECRET=""

Nota

Sem as variáveis do R2, só o upload de arquivos do QuickBrick Studio falha — com a mensagem "Armazenamento R2 não configurado". O restante da plataforma funciona normalmente.

3. Banco de dados#

O schema é definido com Drizzle em db/schema/ e as migrações ficam em drizzle/. Com o DATABASE_URL configurado, aplique as migrações:

npm run db:migrate

Para inspecionar os dados, abra o Drizzle Studio:

npm run db:studio

Os detalhes de modelagem e o fluxo para criar novas migrações estão em Banco de dados.

Atenção

Confirme para qual banco o DATABASE_URL aponta antes de rodar db:migrate ou db:push. Nunca aplique alterações destrutivas em produção sem autorização.

4. Clerk#

1. Crie uma aplicação no painel do Clerk e copie as chaves para o .env.local.
2. Ative Organizations — cada equipe do RoboStage é uma organização do Clerk.
3. Em Webhooks, crie um endpoint apontando para /api/webhooks/clerk com os eventos user.*, organization.updated, organization.deleted e organizationMembership.*. Copie o signing secret para CLERK_WEBHOOK_SECRET.

Dica

Em desenvolvimento local o webhook não alcança sua máquina sem um túnel público. Não tem problema: na primeira ação autenticada, requireAuthenticatedUser() cria a linha do usuário no banco se ela ainda não existir.

Veja Autenticação e permissões para o fluxo completo.

5. Rodar#

npm run dev

O servidor sobe com Turbopack em http://localhost:3000.

Scripts disponíveis#

Testes#

npm test

Os testes ficam em tests/ e rodam contra um Postgres em memória (PGlite) com o schema real do projeto. O Clerk é simulado em tests/setup.ts, então nenhuma chave ou banco externo é necessário.

Problemas comuns#

DATABASE_URL não foi encontrada — o Drizzle Kit lê .env.local. Confira se o arquivo está na raiz e se a variável está escrita exatamente assim.

violates foreign key constraint ... users — o usuário do Clerk ainda não existe na tabela users. Isso é resolvido automaticamente na primeira ação autenticada; se persistir, verifique o webhook do Clerk.

401 Não autenticado em chamadas fetch — rotas protegidas de API e Server Actions respondem 401 em JSON (em vez de redirecionar) quando não há sessão. Faça login antes de testar.