Setup local
Como rodar o Covil do Mineiro do zero na sua máquina.
Pré-requisitos
- Node.js 20+ e npm.
- Um projeto no Supabase (gratuito serve para dev).
- (Opcional) Para exercitar o checkout PIX: o sandbox do Sicoob
(
SICOOB_ENV=sandbox, o padrão) valida o fluxo sem certificado — basta umaSICOOB_PIX_KEY(oSICOOB_CLIENT_IDé opcional no sandbox).
Passo a passo
# 1. Instale as dependências
npm install
# 2. Crie o arquivo de ambiente
cp .env.example .env.local-
Preencha o
.env.local(ver a tabela abaixo). O mínimo para o site público subir é o bloco do Supabase. -
Aplique o schema no SQL Editor do Supabase, na ordem das migrations (ver
banco-de-dados.md), começando porsupabase/migrations/20260407120000_initial_covil.sql, e depois osupabase/seed.sql. -
Após o primeiro cadastro, promova seu usuário a administrador:
update public.profiles set role = 'super_admin' where id = '<auth_user_uuid>'; -
Rode o projeto:
npm run devAcesse
http://localhost:3000. O admin fica em/admin.
Sem as variáveis do Supabase, o site público usa fallback local (
src/data/site-fallback.ts) e o admin redireciona ao login com aviso desetup. Ou seja: dá para ver o site sem banco, mas não para operar.
Variáveis de ambiente
| Variável | Visibilidade | Para que serve |
|---|---|---|
NEXT_PUBLIC_SITE_URL | pública | URL base (metadata, retorno do pagamento PIX, QR da carteirinha). Dev: http://127.0.0.1:3000 |
NEXT_PUBLIC_SUPABASE_URL | pública | Endpoint do Supabase |
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY | pública | Chave publishable/anon do Supabase |
SUPABASE_SERVICE_ROLE_KEY | secreta | Client admin (ignora RLS) — webhook e escrita de pedidos |
SICOOB_ENV | servidor (opcional) | sandbox (padrão) ou production. Sandbox valida o fluxo PIX sem certificado |
SICOOB_PIX_KEY | secreta | Chave PIX da conta recebedora (onde as cobranças caem). Obrigatória |
SICOOB_CLIENT_ID | secreta | client_id do portal developers.sicoob.com.br (opcional no sandbox) |
SICOOB_CERT_PFX_BASE64 | secreta | Certificado ICP-Brasil A1 (.pfx em base64) para o mTLS — só produção |
SICOOB_CERT_PASSWORD | secreta | Senha do .pfx — só produção |
GMAIL_USER | secreta | E-mail remetente (Gmail SMTP) |
GMAIL_APP_PASSWORD | secreta | Senha de app do Google (espaços são removidos automaticamente) |
CARD_SIGNING_SECRET | secreta | HMAC do código de autenticidade da carteirinha (cai para a service role se vazio) |
NEXT_PUBLIC_GA_ID | pública (opcional) | ID do Google Analytics 4 (sem ela, o GA é no-op) |
Rodar os testes
npm run typecheck # tipos
npm run test # unitários (Vitest)
npm run e2e # end-to-end (Playwright; sobe o dev server sozinho)Dicas
- Para virar sócio de teste: crie o usuário, e como
super_adminaprove em/admin/usuarios(isso ativa a associação e credita o bônus de boas-vindas). - Assets da marca ficam em
public/brands.