Ir para o conteúdo principal

Manual de instalação

Este manual descreve como instalar o Business Intelligence (BI) da CEBI em um Windows Server. Ele se destina à equipe de infraestrutura (TI).

Versão de referência: 2026.10.7.1 — pacote BI-2026.10.7.1.zip.

Visão geral

O BI tem duas partes obrigatórias, publicadas no IIS do mesmo servidor, e uma parte opcional para demonstrações:

Parte Pasta no pacote Porta padrão Função
API do BI api/ 5080 Conversa com o banco Oracle, busca os dados das fontes e atende a tela.
Tela (frontend) frontend/ 5173 A aplicação que os usuários abrem no navegador.
APIs de demonstração api-demo/ 8092 e 8093 Dados fictícios para apresentações (opcional).

Importante: a tela procura a API no mesmo servidor, na porta 5080 (se a tela abre em http://servidor:5173, ela chama http://servidor:5080/api). Para usar outro servidor ou outra porta para a API, é preciso gerar a tela de novo — fale com a equipe do BI.

Conteúdo do pacote

BI-2026.10.7.1/
├── INSTALAR.bat          → instalação automática (recomendada)
├── Instalar-BI.ps1       → script executado pelo INSTALAR.bat
├── api/                  → API do BI (.NET 8), já compilada
├── frontend/             → tela do BI (arquivos estáticos), já compilada
├── api-demo/             → APIs de demonstração (Node.js)
└── README-INSTALACAO.md  → este guia, em texto

1. Pré-requisitos

Item Observação
Windows Server 2016 ou mais novo 2019 ou 2022 recomendados.
IIS O instalador instala sozinho, se faltar (inclui Application Initialization).
.NET 8 – ASP.NET Core Hosting Bundle https://dotnet.microsoft.com/download/dotnet/8.0 → coluna ASP.NET Core Runtime → Windows → Hosting Bundle. Deve ser instalado depois do IIS (se o IIS for instalado depois, rode o instalador do Hosting Bundle de novo e escolha Reparar).
IIS URL Rewrite https://www.iis.net/downloads/microsoft/url-rewrite
Node.js 18+ (LTS) https://nodejs.org — somente para as APIs de demonstração.
Acesso ao Oracle O servidor precisa alcançar o banco (padrão 192.168.4.2, porta 1521, serviço bi).
Usuário no Oracle Schema próprio do BI com permissão para criar tabelas e quota no tablespace — a API cria as tabelas sozinha na primeira inicialização.
Portas livres 5080 e 5173 (BI) e 8092/8093 (demonstração).

O driver do Oracle já vem dentro da API — não é preciso instalar o Oracle Client no servidor.

2. Instalação automática (recomendada)

  1. Instale os pré-requisitos acima (Hosting Bundle, URL Rewrite e Node.js).
  2. Copie o BI-2026.10.7.1.zip para o servidor e extraia o zip inteiro.
  3. Dê dois cliques em INSTALAR.bat. Ele pede permissão de administrador sozinho.
  4. Responda às perguntas:
    • Oracle: servidor, porta, serviço, usuário e senha (o instalador testa a conexão);
    • Administrador inicial do BI: nome, e-mail e senha.
  5. Aguarde a etapa 8/8 – Testando. Ao final aparece "BI INSTALADO COM SUCESSO" e o endereço de acesso para os usuários.

O que o instalador faz

Etapa Ação
1/8 Confere Windows, IIS, Hosting Bundle, URL Rewrite, Node.js e se as portas estão livres. Instala o IIS, se faltar.
2/8 Pede os dados do Oracle (e testa o acesso) e do administrador inicial.
3/8 Copia a aplicação para C:\BI (api, frontend, api-demo).
4/8 Cria C:\BI\api\appsettings.Production.json com uma chave de segurança aleatória e os endereços do servidor liberados; o arquivo fica legível só por administradores e pela própria API.
5/8 Publica no IIS os sites BI-API (porta 5080) e BI-Web (porta 5173). A API fica sempre ligada (tem rotina de atualização automática das fontes) e guarda as chaves de criptografia em C:\BI\dados\chaves.
6/8 Libera as portas 5080 e 5173 no firewall do Windows.
7/8 APIs de demonstração: cadastra os nomes api.saneamento.cebi e api.os.cebi e cria tarefas agendadas que as deixam ligadas sozinhas, inclusive após reiniciar o servidor.
8/8 Testa a API, a tela e as APIs de demonstração e mostra os endereços de acesso.

Opções do instalador

Executar pelo PowerShell como administrador:

Opção Uso
.\Instalar-BI.ps1 -InstallDir D:\BI Instala em outra pasta.
.\Instalar-BI.ps1 -SemDemo Não configura as APIs de demonstração.
.\Instalar-BI.ps1 -UrlsExtras "http://bi.cebi.local:5173" Libera um endereço extra (por exemplo, um nome cadastrado no DNS).

O log de cada execução fica em C:\ProgramData\BI-instalacao-<data>.log (as senhas digitadas não são gravadas).

Segurança: a senha inicial do administrador é apagada do arquivo de configuração ao final de uma instalação bem-sucedida — ela só é usada na primeira inicialização. Troque essa senha no primeiro acesso.

3. APIs de demonstração

São usadas nas apresentações: a fonte de dados é cadastrada ao vivo no BI. Como quem busca os dados é a API do BI (no servidor, não no navegador), elas precisam rodar no mesmo servidor da API do BI.

O INSTALAR.bat já as configura. Para instalar ou atualizar somente as APIs de demonstração, use o pacote pequeno BI-demo-2026.10.7.1.zip: extraia e dê dois cliques em INSTALAR-DEMO.bat.

API Endereço para cadastrar no BI
Água/Esgoto http://api.saneamento.cebi:8092/v1/ligacoes
Ordens de Serviço http://api.os.cebi:8093/v1/ordens
  • Os nomes api.saneamento.cebi e api.os.cebi são cadastrados no arquivo hosts do próprio servidor (apontando para ele mesmo). Como alternativa, podem ser cadastrados no DNS da empresa.
  • As portas 8092/8093 não precisam ser liberadas no firewall.
  • No servidor, as APIs aparecem no Agendador de Tarefas como "BI - API Demo Agua" e "BI - API Demo Ordens de Servico".
  • Plano B (sem Node.js): a API do BI já traz dados fictícios embutidos: http://localhost:5080/api/demo/vendas.

4. Verificar a instalação

  1. No navegador, acesse http://<servidor>:5173.
  2. Entre com o e-mail e a senha do administrador.
  3. Em Fontes de Dados → + Nova Fonte, cadastre http://api.saneamento.cebi:8092/v1/ligacoes, clique em Testar conexão e confirme a mensagem "Conexão OK".
  4. O rodapé da tela mostra a versão instalada (ex.: Versão: 2026.10.7.1).

5. Solução de problemas

Sintoma Causa provável Solução
Instalador para em "Falta o .NET 8 – ASP.NET Core Hosting Bundle" Hosting Bundle ausente ou instalado antes do IIS. Instale (ou Repare) o Hosting Bundle e rode o INSTALAR.bat de novo.
"A API não respondeu" na etapa 8/8 Oracle inacessível ou usuário/senha incorretos. Conferir C:\BI\api\appsettings.Production.json e o acesso ao Oracle. Detalhes: Visualizador de Eventos → Logs do Windows → Aplicativo (origem IIS AspNetCore Module V2).
Ao cadastrar fonte: "No such host is known (api.saneamento.cebi…)" Os nomes das APIs de demonstração não estão cadastrados no servidor. Rodar o INSTALAR-DEMO.bat (ou o INSTALAR.bat) no servidor da API do BI.
Ao cadastrar fonte: conexão recusada A API de demonstração não está ligada. Conferir as tarefas "BI - API Demo…" no Agendador de Tarefas e se o Node.js está instalado.
Aviso "CONFLITO: a porta … já é usada por …" Outro sistema do servidor usa a porta. Avisar a equipe do BI para gerar o pacote com outra porta.
Tela abre, mas mostra "Não foi possível conectar ao servidor" A API (porta 5080) está parada ou bloqueada no firewall. Conferir o site BI-API no Gerenciador do IIS e a regra de firewall "BI - API (5080)".

6. Instalação manual (sem o instalador)

Use apenas se não for possível executar o INSTALAR.bat.

  1. API: copie a pasta api/ para o servidor. Copie appsettings.Production.example.json para appsettings.Production.json e preencha:
    • ConnectionStrings:Oracle — usuário, senha e endereço do Oracle;
    • Jwt:Key — chave secreta com no mínimo 32 caracteres, única deste servidor;
    • Seed:AdminEmail / Seed:AdminPassword — administrador inicial (criado só se o banco não tiver usuários);
    • Frontend:BaseUrl — endereço(s) da tela, separados por vírgula (ex.: http://servidor:5173);
    • DataProtection:KeysPath — pasta fixa para as chaves de criptografia (ex.: C:\BI\dados\chaves), com permissão de escrita para a API.
  2. Publique a pasta api/ no IIS (porta 5080), com pool de aplicativos sem código gerenciado, sempre ligado (AlwaysRunning, idle timeout 0) e preload habilitado. O web.config já está pronto.
  3. Tela: publique a pasta frontend/ no IIS (porta 5173). O web.config incluído já configura as rotas (requer o URL Rewrite).
  4. Libere as portas 5080 e 5173 no firewall.

Na primeira inicialização, a API cria as tabelas no Oracle e o usuário administrador automaticamente.

7. Segurança

  • Troque a senha inicial do administrador no primeiro acesso.
  • Não compartilhe o appsettings.Production.json: ele contém a senha do Oracle e a chave de segurança.
  • Mantenha Auth:ReturnDevLinks como false em produção.
  • Avalie publicar com HTTPS (certificado no IIS).
  • Se o servidor usar o mesmo banco Oracle de outro ambiente do BI, painéis e usuários são mantidos, mas fontes de dados com senha/token precisam ter essa senha informada de novo (cada servidor tem as próprias chaves de criptografia).