--- title: 17. Instalação, backup e restauração slug: 17-instalacao-backup-e-restauracao docTags: createdAt: 2026-10-09T19:14:00.069Z --- 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 1. 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. 2. 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. 3. Modo interno: em deploy/compose/bussola, copie .env.example para .env, proteja-o com chmod 600 e preencha todos os valores marcados com REPLACE\_. 4. 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". 5. Modo nuvem: confira o que será aplicado com kubectl kustomize k8s/bussola. 6. 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. 7. 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. 8. Confira a primeira subida: abra https\://\/portal/ e verifique o redirecionamento ao provedor de identidade. 9. Depois do login, verifique que **Mapa estratégico**, **Indicadores** e **Dados** abrem para um usuário com os cargos adequados. 10. 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. 11. 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\://\/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 1. 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). 2. 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. 3. Configure o alerta: nenhuma linha "status":"ok" nas últimas 26 horas, ou código de saída diferente de 0. 4. Para restaurar, prepare um servidor novo com PostgreSQL 16, os bancos vazios (bussola e bussola\_master) e o usuário da aplicação. 5. 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. 6. 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. 7. Suba o produto com a **mesma** RESOURCE\_TENANT\_SECURITY\_KEY da origem. 8. 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=\ (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 1. Escolha um conjunto recente no destino do backup. 2. Restaure-o num ambiente limpo, seguindo a seção BSC-INS-02. 3. Anote a data, quem executou, o ambiente, o nome do conjunto, o tamanho e a duração. 4. Registre as contagens das tabelas-chave na origem e no destino e confirme que são iguais. 5. Registre a evidência de indicador aberta e a conexão testada em **Dados › Conexões**. 6. 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.