Solução de Problemas (Troubleshooting)

Esta página reúne soluções para os incidentes mais comuns encontrados durante a execução local do bdot CLI e da infraestrutura de containers.

---

Conflito de Porta (Porta já em uso)

Sintoma: Erro ao iniciar a plataforma (bdot up), indicando que as portas :81 (HTTP) ou :443 (HTTPS) já estão ocupadas por outro processo no host.

Solução:

Altere as portas padrão de execução através do assistente de configuração:

1. Execute o assistente:

   Terminal

   bdot setup

2. Selecione Editar configuração (ou Configuração avançada).

3. Navegue até o grupo Rede e altere Porta HTTP (ex: de 81 para 8080) ou Porta HTTPS (ex: de 443 para 8443).

4. Salve a configuração e reinicie os serviços:

   Terminal

   bdot down && bdot up

---

Hostname não resolve (bdot.local)

Sintoma: O navegador ou os comandos de terminal não conseguem acessar o endereço http://bdot.local:81 ou https://bdot.local.

Solução no Linux:

Registrar o hostname no daemon do Avahi/mDNS (requer privilégios de superusuário):

Terminal

sudo bdot update-hostname --hostname bdot.local --port 81

Solução Universal (Fallback via /etc/hosts):

Mapeie o domínio local diretamente no arquivo de hosts da sua máquina:

Terminal

echo "127.0.0.1 bdot.local" | sudo tee -a /etc/hosts

---

Problemas com Certificado TLS Autoassinado

Sintoma: O navegador exibe alertas de segurança no acesso HTTPS, ou as requisições via curl/ferramentas de API falham devido ao certificado bdot.crt.

Solução:

1. No navegador, aceite a exceção de segurança para certificados autoassinados em ambiente de desenvolvimento local.

2. Se precisar regenerar os certificados autoassinados da CLI do zero:

   Terminal

   bdot down
   rm -rf ~/.bdot/certs/
   bdot up

---

Um ou mais serviços não ficam saudáveis (Unhealthy)

Sintoma: O bdot up trava no healthcheck aguardando bdot-sso ou bdot-database, ou o bdot status exibe ícones de erro (✘).

Solução:

1. Verifique os logs do container específico via Docker:

   Terminal

   docker logs bdot-database --tail 50
   docker logs bdot-sso --tail 50

2. Tente reiniciar o container com falha pontualmente:

   Terminal

   docker compose -p bdot-ce restart bdot-sso

3. Verifique se o Docker Engine atende aos requisitos mínimos de memória RAM (mínimo de 4 GB dedicados ao Docker).

---

Perda da Senha do Administrador do SSO / Banco

Sintoma: Acesso bloqueado às rotas administrativas por falta da senha do usuário admin.

Solução:

As senhas geradas dinamicamente ficam armazenadas em arquivos de acesso restrito no workspace local. Para visualizar a senha do administrador do SSO/Keycloak, execute:

Terminal

cat ~/.bdot/.bdot_secrets/bdot_sso_admin_password

Para a senha de administração do banco PostgreSQL (admin):

Terminal

cat ~/.bdot/.bdot_secrets/bdot_db_admin_password

---

Reset Completo do Ambiente (Recomeçar do zero)

Sintoma: Inconsistência nos dados de estado (state.json), segredos corrompidos ou necessidade de limpar todos os volumes locais do Docker.

Caution

Esta ação removerá todos os dados gravados nos bancos de dados locais e os segredos gerados.

Solução:

Execute a sequência de comandos para redefinir completamente o workspace:

Terminal

# 1. Parar a plataforma e remover os containers
bdot down

# 2. Remover os arquivos de estado local e segredos
rm -rf ~/.bdot/.bdot_secrets/ ~/.bdot/state.json ~/.bdot/certs/

# 3. Reconfigurar e subir a plataforma
bdot setup --fast-config
bdot up