7.4 KiB
7.4 KiB
🏠 CONFIGURAÇÃO CONVEX LOCAL - SGSE
Data: 27/10/2025
Modo: Desenvolvimento Local (não nuvem)
✅ O QUE FOI CORRIGIDO
O erro 500 estava acontecendo porque o frontend estava tentando conectar ao Convex Cloud, mas o backend está rodando localmente.
Problema identificado:
❌ Frontend tentando conectar: https://sleek-cormorant-914.convex.cloud
✅ Backend rodando em: http://127.0.0.1:3210
Solução aplicada:
- ✅ Criado arquivo
.envno frontend com URL local correta - ✅ Adicionado
setupConvex()no layout principal - ✅ Configurado para usar Convex local na porta 3210
📂 ARQUIVOS CONFIGURADOS
1. Backend - packages/backend/.env
BETTER_AUTH_SECRET=+Nfg4jTxPv1giF5MlmyYTxpU/VkS3QaDOvgSWd+QmbY=
SITE_URL=http://localhost:5173
- ✅ Secret configurado
- ✅ URL da aplicação definida
- ✅ Roda na porta 3210 (padrão do Convex local)
2. Frontend - apps/web/.env
PUBLIC_CONVEX_URL=http://127.0.0.1:3210
PUBLIC_SITE_URL=http://localhost:5173
- ✅ Conecta ao Convex local
- ✅ URL pública para autenticação
3. Layout Principal - apps/web/src/routes/+layout.svelte
// Configurar Convex para usar o backend local
setupConvex(PUBLIC_CONVEX_URL);
- ✅ Inicializa conexão com Convex local
🚀 COMO INICIAR O PROJETO
Método Simples (Recomendado):
cd "C:\Users\Deyvison\OneDrive\Desktop\Secretaria de Esportes\Tecnologia da Informacao\SGSE\sgse-app"
bun dev
Isso inicia automaticamente:
- 🔹 Backend Convex na porta 3210
- 🔹 Frontend SvelteKit na porta 5173
Método Manual (Dois terminais):
Terminal 1 - Backend:
cd "C:\Users\Deyvison\OneDrive\Desktop\Secretaria de Esportes\Tecnologia da Informacao\SGSE\sgse-app\packages\backend"
bunx convex dev
Terminal 2 - Frontend:
cd "C:\Users\Deyvison\OneDrive\Desktop\Secretaria de Esportes\Tecnologia da Informacao\SGSE\sgse-app\apps\web"
bun run dev
🌐 ACESSAR A APLICAÇÃO
Após iniciar os servidores, acesse:
URL Principal: http://localhost:5173
🔍 VERIFICAR SE ESTÁ FUNCIONANDO
✅ Backend Convex (Terminal 1):
Deve mostrar:
✔ Convex functions ready!
✔ Serving at http://127.0.0.1:3210
✅ Frontend (Terminal 2):
Deve mostrar:
VITE v... ready in ...ms
➜ Local: http://localhost:5173/
✅ No navegador:
- ✅ Página carrega sem erro 500
- ✅ Dashboard aparece normalmente
- ✅ Dados são carregados do Convex local
📊 ARQUITETURA LOCAL
┌─────────────────────────────────────────┐
│ Navegador (localhost:5173) │
│ Frontend SvelteKit │
└────────────────┬────────────────────────┘
│ HTTP
│ setupConvex(http://127.0.0.1:3210)
↓
┌─────────────────────────────────────────┐
│ Convex Local (127.0.0.1:3210) │
│ Backend Convex │
│ ┌─────────────────────┐ │
│ │ Banco de Dados │ │
│ │ (SQLite local) │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────┘
⚠️ IMPORTANTE: MODO LOCAL vs NUVEM
Modo Local (Atual):
- ✅ Convex roda no seu computador
- ✅ Dados armazenados localmente
- ✅ Não precisa de internet para funcionar
- ✅ Ideal para desenvolvimento
- ✅ Porta padrão: 3210
Modo Nuvem (NÃO estamos usando):
- ❌ Convex roda nos servidores da Convex
- ❌ Dados na nuvem
- ❌ Precisa de internet
- ❌ Requer configuração adicional
- ❌ URL: https://[projeto].convex.cloud
🔧 SOLUÇÃO DE PROBLEMAS
Erro 500 ainda aparece:
- Pare todos os servidores (Ctrl+C)
- Verifique o arquivo .env:
Deve mostrar:
cd apps\web Get-Content .envPUBLIC_CONVEX_URL=http://127.0.0.1:3210 - Inicie novamente:
cd ..\.. bun dev
"Cannot connect to Convex":
- Verifique se o backend está rodando:
# Deve mostrar processo na porta 3210 netstat -ano | findstr :3210 - Se não estiver, inicie o backend:
cd packages\backend bunx convex dev
"Port 3210 already in use":
Já existe um processo usando a porta. Mate o processo:
# Encontrar PID
netstat -ano | findstr :3210
# Matar processo (substitua PID)
taskkill /PID <PID> /F
Dados não aparecem:
- Verifique se há dados no banco local
- Execute o seed (popular banco):
cd packages\backend\convex # (Criar script de seed se necessário)
📝 CHECKLIST DE VERIFICAÇÃO
- Backend Convex rodando na porta 3210
- Frontend rodando na porta 5173
- Arquivo
.envexiste emapps/web/ PUBLIC_CONVEX_URL=http://127.0.0.1:3210está correto- Navegador abre sem erro 500
- Dashboard carrega os dados
- Nenhum erro no console do navegador (F12)
🎯 DIFERENÇAS DOS ARQUIVOS .env
Backend (packages/backend/.env):
# Usado pelo Convex local
BETTER_AUTH_SECRET=... (secret criptográfico)
SITE_URL=http://localhost:5173 (URL do frontend)
Frontend (apps/web/.env):
# Usado pelo SvelteKit
PUBLIC_CONVEX_URL=http://127.0.0.1:3210 (URL do Convex local)
PUBLIC_SITE_URL=http://localhost:5173 (URL da aplicação)
Importante: As variáveis com prefixo PUBLIC_ no SvelteKit são expostas ao navegador.
🔐 SEGURANÇA
Arquivos .env:
- ✅ Estão no
.gitignore - ✅ Não serão commitados
- ✅ Secrets não vazam
Para Produção (Futuro):
Quando for colocar em produção:
- 🔐 Gerar novo secret de produção
- 🌐 Configurar Convex Cloud (se necessário)
- 🔒 Usar variáveis de ambiente do servidor
📞 COMANDOS ÚTEIS
# Verificar se portas estão em uso
netstat -ano | findstr :3210
netstat -ano | findstr :5173
# Matar processo em uma porta
taskkill /PID <PID> /F
# Limpar e reinstalar dependências
bun install
# Ver logs do Convex
cd packages\backend
bunx convex dev --verbose
# Ver logs do frontend (terminal do Vite)
cd apps\web
bun run dev
✅ RESUMO
| Componente | Status | Porta | URL |
|---|---|---|---|
| Backend Convex | ✅ Local | 3210 | http://127.0.0.1:3210 |
| Frontend SvelteKit | ✅ Local | 5173 | http://localhost:5173 |
| Banco de Dados | ✅ Local | - | SQLite (arquivo local) |
| Autenticação | ✅ Config | - | Better Auth |
🎉 CONCLUSÃO
Tudo configurado para desenvolvimento local!
- ✅ Erro 500 corrigido
- ✅ Frontend conectando ao Convex local
- ✅ Backend rodando localmente
- ✅ Pronto para desenvolvimento
Para iniciar:
bun dev
Para acessar:
http://localhost:5173
Criado em: 27/10/2025 às 09:15
Modo: Desenvolvimento Local
Status: ✅ Pronto para uso
🚀 Bom desenvolvimento!