Solução de Problemas

Guia de diagnóstico e resolução dos erros mais comuns encontrados durante a instalação e execução do Urbis.

🗄️ Banco de Dados e Docker

Erro: Conexão Recusada (`ECONNREFUSED 127.0.0.1:5432`)

Causa: O container do PostgreSQL não está em execução ou há conflito de porta com outra instância local.

Solução:

Verifique se o Docker está ativo e execute docker ps.
Inicie os containers de infraestrutura:
```
pnpm composer:up
```
Se a porta 5432 estiver ocupada por um PostgreSQL local na máquina host, pare o serviço local ou configure outra porta no arquivo .env.

🔐 Certificados SSL e OIDC (Accounts)

Erro: `SSL certificates not found in apps/accounts root`

Causa: Os arquivos de certificado TLS necessários para o domínio local de autenticação não foram encontrados.

Solução: Execute o mkcert para gerar os certificados na raiz de apps/accounts:

mkcert -key-file apps/accounts/conta.urbis.prefeitura.sp.gov.br-key.pem \
       -cert-file apps/accounts/conta.urbis.prefeitura.sp.gov.br.pem \
       conta.urbis.prefeitura.sp.gov.br localhost 127.0.0.1

Erro: `EACCES: permission denied` ao executar `pnpm dev:ssl`

Causa: O proxy SSL escuta na porta 443 (padrão HTTPS), o que pode exigir privilégios de administrador no Linux/macOS.

Solução: Execute o comando com elevação de privilégios:

sudo pnpm dev:ssl

Causa: A URL da aplicação frontend não corresponde à lista de origens autorizadas no Provedor OIDC.

Solução: Verifique se a URL de redirecionamento está configurada no backend (apps/api/src/auth/oidc/oidc.config.ts) e certifique-se de acessar pelo host correto mapeado no arquivo /etc/hosts.

📦 Armazenamento de Arquivos e MinIO S3

Erro: Uploads falham com `NoSuchBucket` ou `Connection Refused`

Causa: O container do MinIO não criou os buckets padrões ou o endpoint S3 não está apontando para http://localhost:9000.

Solução:

Acesse o console do MinIO em http://localhost:9001 (login: minioadmin / senha: minioadmin123).
Verifique se os buckets public, private e uploads existem.

No arquivo apps/api/.env, certifique-se de ter:

AWS_S3_ENDPOINT=http://localhost:9000
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin123
S3_BUCKET_NAME=public

⚡ Turborepo & Cache de Build

Alterações em pacotes compartilhados (`packages/*`) não refletem nos apps

Causa: O Turborepo pode estar servindo artefatos em cache.

Solução: Force uma reconstrução completa ignorando o cache:

pnpm build --force

Ou remova a pasta de cache do Turbo:

rm -rf .turbo apps/*/.turbo packages/*/.turbo

Solução de Problemas

On this page