17. Instalação, backup e restauração
O Bússola/BSC pode ser instalado de duas formas: interna, num servidor do ambiente da empresa com Docker Compose, ou em nuvem, num cluster Kubernetes. As peças instaladas são as mesmas nos dois modos: banco PostgreSQL 16, mensageria, backend, portal web, entrada TLS e o serviço de backup.
Não há aplicativo de loja. Computador, tablet e celular usam o mesmo portal web responsivo, que o navegador permite instalar como aplicativo ("Instalar aplicativo" ou "Adicionar à tela inicial").
Este capítulo é para o Administrador do sistema e a equipe de infraestrutura da empresa.
17.1 Instalação interna (no ambiente da empresa) e em nuvem
ID BSC-INS-01
Para que serve
Descreve o que é instalado, os pré-requisitos e os comandos de instalação nos dois modos. As peças: banco PostgreSQL 16 com dois bancos (mestre, de controle de migração, e o banco de dados da organização); mensageria (o produto sobe sem ela, mas avisos e notificações dependem dela); backend (aplica as migrações do banco na subida); portal web responsivo servido em /portal/; entrada TLS (nginx no modo interno ou o Ingress do cluster), único ponto exposto; e o serviço de backup.
Recursos mínimos no modo interno, tudo num servidor: 4 vCPU, 8 GB de RAM e 50 GB de disco para banco e anexos, mais o espaço das cópias locais de backup.
Quem usa: Administrador do sistema.
Passo a passo
- Providencie os pré-requisitos: provedor de identidade compatível com OIDC (por exemplo, Keycloak), nome público com certificado TLS (por exemplo, bussola.exemplo.com.br), destino de backup e liberações de rede.
- Gere os segredos: senha do banco, RESOURCE_TENANT_SECURITY_KEY (cifra as credenciais guardadas; guarde uma cópia fora do backup) e FINANCE_PIX_WEBHOOK_SECRET.
- Modo interno: em deploy/compose/bussola, copie .env.example para .env, proteja-o com chmod 600 e preencha todos os valores marcados com REPLACE_.
- Modo interno: copie o certificado e a chave para tls/fullchain.pem e tls/privkey.pem, rode docker compose up -d e acompanhe docker compose logs -f backend até aparecer "Started Application".
- Modo nuvem: confira o que será aplicado com kubectl kustomize k8s/bussola.
- Modo nuvem: crie no namespace bussola o segredo erp-backend-secret a partir de backend.env, o segredo do backup (a partir de secret.backup.yaml.example) e o segredo TLS bussola-tls; depois aplique o overlay com kubectl -n bussola apply -k k8s/bussola.
- Modo nuvem: ajuste no overlay as imagens, o host e a classe do Ingress, as variáveis KEYCLOAK_* e KAFKA_BOOTSTRAP_SERVERS no configmap.backend.yaml e a classe de armazenamento do volume.
- Confira a primeira subida: abra https://<host>/portal/ e verifique o redirecionamento ao provedor de identidade.
- Depois do login, verifique que Mapa estratégico, Indicadores e Dados abrem para um usuário com os cargos adequados.
- Provisione a base de leitura com scripts/ops/bsc-leitura/provision-pg.sql, informe TENANT_READER_PASS, reinicie o backend e confira que o console SQL lê a visão indicator_v.
- Confira o primeiro backup: uma linha com "status":"ok" no log do serviço de backup e o conjunto gravado no destino.
Observações
- O perfil de segurança da instalação não tem login próprio e recusa subir sem KEYCLOAK_ISSUER_URI e KEYCLOAK_JWK_URI. O provedor de identidade deve emitir tokens assinados com a reivindicação que identifica o ambiente da organização.
- No modo interno, o banco da organização é criado na primeira subida e o backend cria os esquemas e aplica as migrações. A primeira subida pode levar minutos.
- Os anexos ficam no volume nomeado bussola-attachments, nunca no diretório temporário do contêiner (sumiriam na primeira troca de imagem). O backup copia esse volume.
- A configuração é a mesma nos dois modos: k8s/bussola/application-bussola.yml, montada em /config/.
- O banco não é publicado na rede. Ferramentas de BI usam a base de leitura própria.
- No modo nuvem, o backend.env leva MASTER_DB_URL/USER/PASS, BUSSOLA_TENANT_ID, TENANT_DB_URL/USER/PASS/SCHEMA, TENANT_READER_PASS, RESOURCE_TENANT_SECURITY_KEY e FINANCE_PIX_WEBHOOK_SECRET.
- No modo nuvem, o backend roda com uma réplica e estratégia Recreate (volume ReadWriteOnce); o agendamento de backup roda no mesmo nó para montar o volume de anexos só para leitura. O PostgreSQL é o gerenciado da empresa, fora do overlay.
- Liberações de rede: entrada HTTPS no nome público; saída para o provedor de identidade, para os sistemas integrados (SEI, SIAFI, Portal da Transparência, mensageria da empresa) e para o destino do backup. Webhooks de entrada chegam em https://<host>/portal/api/integrations/inbound//.
- O ambiente de simulação para treinamento e homologação das integrações não é instalado em produção.
17.2 Backup diário e restauração
ID BSC-INS-02
Para que serve
O backup gera, toda noite, um conjunto com data e hora UTC no nome (por exemplo, bussola-20261009T040000Z/) e o envia ao destino definido pela empresa. O conjunto contém: tenant.dump (banco de dados da organização), master.dump (banco mestre, na instalação dedicada), attachments.tar.gz (anexos: evidências de indicador, de entrega, atas) e SHA256SUMS (somas de conferência, gravado por último).
A restauração é feita num ambiente limpo, com o roteiro bsc-restore.sh, que confere cada arquivo antes de restaurar.
Quem usa: Administrador do sistema.
Passo a passo
- Defina o destino em BACKUP_DEST_KIND: S3 (armazenamento de objetos compatível; informe endereço, balde, prefixo e chave com PutObject e GetObject) ou PATH (diretório montado, como NFS).
- Confirme o agendamento: no modo interno, o serviço backup usa BACKUP_CRON (padrão 0 1 * * *) com TZ=America/Sao_Paulo; no modo nuvem, o CronJob bussola-backup usa timeZone America/Sao_Paulo. Ambos rodam às 01:00 de Brasília.
- Configure o alerta: nenhuma linha "status":"ok" nas últimas 26 horas, ou código de saída diferente de 0.
- Para restaurar, prepare um servidor novo com PostgreSQL 16, os bancos vazios (bussola e bussola_master) e o usuário da aplicação.
- Execute o bsc-restore.sh no contêiner da imagem bussola-backup:16, com PGHOST, PGUSER, PGPASSWORD, RESTORE_TENANT_DB, RESTORE_MASTER_DB e RESTORE_ATTACHMENTS_DIR. Com RESTORE_SOURCE_KIND=S3 ele baixa o conjunto pelo nome; com PATH, recebe o diretório.
- Recrie os papéis de leitura com senhas novas, usando scripts/ops/bsc-leitura/provision-pg.sql, e informe a nova senha na configuração.
- Suba o produto com a mesma RESOURCE_TENANT_SECURITY_KEY da origem.
- Confira: contagens das tabelas-chave iguais às da origem (indicadores, medições, objetivos), uma evidência de indicador abre (prova os anexos), Dados › Conexões testa uma conexão com sucesso (prova a chave) e o console SQL lê indicator_v (prova a base de leitura).
Observações
- Ficam fora do backup, de propósito, e devem ser guardados à parte com dono nomeado: a chave RESOURCE_TENANT_SECURITY_KEY (num cofre de segredos, fora do destino do backup), os papéis de banco de leitura e de BI (recriados na restauração) e o arquivo .env ou os Secrets do Kubernetes.
- Sem a mesma chave de cifragem, o produto sobe, mas toda credencial gravada (conexões de banco, integrações) deixa de abrir, sem aviso.
- Em servidor compartilhado, o backup leva só os esquemas listados em BACKUP_TENANT_SCHEMAS e as respectivas bases de leitura; dados de outros ambientes não vão para o destino.
- Cifragem no destino S3: BACKUP_S3_SSE=AES256. Retenção remota: regra de ciclo de vida do balde (S3) ou BACKUP_DEST_KEEP=<n> (PATH).
- Sem TZ, o horário escorrega: o agendador do contêiner usa UTC e "0 1" viraria 22:00 de Brasília. O horário de 01:00 evita disputa com as rotinas noturnas do produto, que começam às 02:00.
- Cada execução grava uma linha JSON no log, com status, código de saída, conjunto, tamanho, soma e destino; o destino nunca leva credencial e o campo de erro diz o passo que falhou.
- Código 3: arquivo corrompido ou que não confere com SHA256SUMS; nada é enviado (no backup) ou tudo é abortado (na restauração). Código 4: destino fora do ar; a cópia fica no disco local, que cresce até o próximo envio bem-sucedido. Código 5: banco de destino com tabelas; a restauração é recusada.
- RESTORE_FORCE=1 só deve ser usado quando o alvo foi conferido por duas pessoas.
- A restauração usa --no-owner --no-privileges: os objetos passam a pertencer ao usuário que conectou.
- Conjunto sem SHA256SUMS no destino é envio incompleto. Se os anexos estão num armazenamento de objetos, o backup deles é a versão ou a replicação do próprio balde.
17.3 Registrar o teste de restauração
ID BSC-INS-03
Para que serve
Uma cópia de segurança só vale se a restauração funciona. A empresa deve fazer restaurações reais periódicas num ambiente separado e registrar cada uma, para comprovar que o backup diário é utilizável.
Quem usa: Administrador do sistema; Leitor/Auditor.
Passo a passo
- Escolha um conjunto recente no destino do backup.
- Restaure-o num ambiente limpo, seguindo a seção BSC-INS-02.
- Anote a data, quem executou, o ambiente, o nome do conjunto, o tamanho e a duração.
- Registre as contagens das tabelas-chave na origem e no destino e confirme que são iguais.
- Registre a evidência de indicador aberta e a conexão testada em Dados › Conexões.
- Guarde o registro junto à documentação de operação da instalação.
Observações
- Uma restauração que sobe o produto mas não abre as conexões indica chave de cifragem diferente da origem.
- Banco de dados SQL Server não é a base padrão do produto; quando usado, o equivalente é o backup nativo com CHECKSUM e COMPRESSION, a verificação com RESTORE VERIFYONLY e o envio do arquivo .bak pelo mesmo destino.