sgse-app/CONFIGURACAO_PRODUCAO.md

🚀 Configuração para Produção - SGSE

Este documento contém as instruções para configurar as variáveis de ambiente necessárias para colocar o sistema SGSE em produção.

---

⚠️ IMPORTANTE - SEGURANÇA

As configurações abaixo são OBRIGATÓRIAS para garantir a segurança do sistema em produção. NÃO pule estas etapas!

---

📋 Variáveis de Ambiente Necessárias

1. BETTER_AUTH_SECRET (OBRIGATÓRIO)

O que é: Chave secreta usada para criptografar tokens de autenticação.

Por que é importante: Sem um secret único e forte, qualquer pessoa pode falsificar tokens de autenticação e acessar o sistema sem autorização.

Como gerar um secret seguro:

Opção A: PowerShell (Windows)

[Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))

Opção B: Linux/Mac

openssl rand -base64 32

Opção C: Node.js

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Exemplo de resultado:

aBc123XyZ789+/aBc123XyZ789+/aBc123XyZ789+/==

---

2. SITE_URL ou CONVEX_SITE_URL (OBRIGATÓRIO)

O que é: URL base da aplicação onde o sistema está hospedado.

Exemplos:

• Desenvolvimento Local: http://localhost:5173
• Produção: https://sgse.pe.gov.br (substitua pela URL real)

---

🔧 Como Configurar no Convex

Passo 1: Acessar o Convex Dashboard

1. Acesse: https://dashboard.convex.dev
2. Faça login com sua conta
3. Selecione o projeto SGSE

Passo 2: Configurar Variáveis de Ambiente

1. No menu lateral, clique em Settings (Configurações)
2. Clique na aba Environment Variables
3. Adicione as seguintes variáveis:

Para Desenvolvimento:

Variável	Valor
BETTER_AUTH_SECRET	(Gere um usando os comandos acima)
SITE_URL	http://localhost:5173

Para Produção:

Variável	Valor
BETTER_AUTH_SECRET	(Gere um NOVO secret diferente do desenvolvimento)
SITE_URL	https://sua-url-de-producao.com.br

Passo 3: Salvar as Configurações

1. Clique em Add para cada variável
2. Clique em Save para salvar as alterações
3. Aguarde o Convex reiniciar automaticamente

---

✅ Verificação

Após configurar as variáveis, as mensagens de ERRO e WARN no terminal devem desaparecer:

❌ Antes (com erro):

[ERROR] 'You are using the default secret. Please set `BETTER_AUTH_SECRET`'
[WARN] 'Better Auth baseURL is undefined. This is probably a mistake.'

✅ Depois (sem erro):

✔ Convex functions ready!

---

🔐 Boas Práticas de Segurança

✅ FAÇA:

1. Gere secrets diferentes para desenvolvimento e produção
2. Nunca compartilhe o BETTER_AUTH_SECRET publicamente
3. Nunca commite arquivos .env com secrets no Git
4. Use secrets fortes com pelo menos 32 caracteres aleatórios
5. Rotacione o secret periodicamente em produção
6. Documente onde os secrets estão armazenados (Convex Dashboard)

❌ NÃO FAÇA:

1. NÃO use "1234" ou "password" como secret
2. NÃO compartilhe o secret em e-mails ou mensagens
3. NÃO commite o secret no código-fonte
4. NÃO reutilize o mesmo secret em múltiplos ambientes
5. NÃO deixe o secret em produção sem configurar

---

🆘 Troubleshooting

Problema: Mensagens de erro ainda aparecem após configurar

Solução:

1. Verifique se as variáveis foram salvas corretamente no Convex Dashboard
2. Aguarde alguns segundos para o Convex reiniciar
3. Recarregue a aplicação no navegador
4. Verifique os logs do Convex para confirmar que as variáveis foram carregadas

Problema: Erro "baseURL is undefined"

Solução:

1. Certifique-se de ter configurado SITE_URL no Convex Dashboard
2. Use a URL completa incluindo http:// ou https://
3. Não adicione barra / no final da URL

Problema: Sessões não funcionam após configurar

Solução:

1. Limpe os cookies do navegador
2. Faça logout e login novamente
3. Verifique se o BETTER_AUTH_SECRET está configurado corretamente

---

📞 Suporte

Se encontrar problemas durante a configuração:

1. Verifique os logs do Convex Dashboard
2. Consulte a documentação do Convex: https://docs.convex.dev
3. Consulte a documentação do Better Auth: https://www.better-auth.com

---

📝 Checklist de Produção

Antes de colocar o sistema em produção, verifique:

• BETTER_AUTH_SECRET configurado no Convex Dashboard
• SITE_URL configurado com a URL de produção
• Secret gerado usando método criptograficamente seguro
• Secret é diferente entre desenvolvimento e produção
• Mensagens de erro no terminal foram resolvidas
• Login e autenticação funcionando corretamente
• Permissões de acesso configuradas
• Backup do secret armazenado em local seguro

---

Data de Criação: 27/10/2025 Versão: 1.0 Autor: Equipe TI SGSE