Pular para conteúdo

Instalador (./install.sh)

O instalador é o caminho recomendado para colocar o Quantix Vision AI em produção. Antes de executar qualquer coisa ele entrevista o administrador, começando pelo dimensionamento (quantos ativos serão geridos nos próximos 24 meses), mostra o ambiente recomendado, verifica o(s) servidor(es), instala tudo com Ansible (no próprio servidor, em outro via SSH ou em um cluster de vários servidores) e termina com o link do assistente de primeira execução. No assistente, o administrador, o certificado HTTPS, o LDAP/AD e o e-mail são configurados pelo navegador. Nenhum arquivo de configuração precisa ser editado.

sudo ./install.sh            # instala neste servidor (pergunta o essencial)
./install.sh                 # a partir de outra máquina: escolha "remote" e informe o servidor
./install.sh plan            # só o dimensionamento: qual ambiente montar
./install.sh expand          # converte uma instalação de host único em cluster distribuído
flowchart LR
  S["ativos em 24 meses<br/>→ ambiente recomendado"] --> A["./install.sh<br/>perguntas"]
  A --> B["preflight<br/>(somente leitura)"]
  B -->|sem falhas| C["Ansible site.yml<br/>Docker, .env, TLS, imagens, compose"]
  C --> D["link /setup#token=…"]
  D --> E["assistente no navegador<br/>admin · organização · TLS · LDAP · e-mail"]
  E --> F["primeiro dispositivo"]

O que você precisa

Item Detalhe
Servidor Linux x86-64 RHEL/Rocky/Alma/Oracle 8–9, Ubuntu 22.04/24.04 ou SLES/openSUSE Leap 15, dimensionado pelo porte (Requisitos)
Acesso root/sudo no servidor. Remoto: SSH com usuário que tenha sudo, de preferência com chave
Controlador a máquina que roda o ./install.sh (pode ser o próprio servidor): Python 3.9+
Imagens acesso ao registro (Docker Hub ou interno), ou acesso a Docker Hub/PyPI/npm para construir no servidor, ou o pacote offline
DNS nome para o endereço público (ex.: quantix.empresa.com.br). O instalador avisa se não resolver
Certificado opcional na instalação: começa com um autoassinado e o da sua CA é enviado no assistente

O install.sh prepara o Ansible automaticamente: usa o do sistema, se for 2.15+, ou cria um ambiente isolado em .install/venv. Em ambientes sem internet, o pacote offline já traz os pacotes necessários.

Perguntas

Etapa Pergunta Padrão
1 Qual a quantidade de ativos que serão geridos nos próximos 24 meses? (VMs, TB de armazenamento, portas de SAN) → ambiente recomendado · topologia (host único ou cluster) respostas anteriores · topologia do plano
2 Host único: instalar neste servidor ou em outro via SSH (host, usuário, porta, chave). Cluster: quantos nós, nome e IP de cada servidor, acesso SSH este servidor
3 Endereço HTTPS de acesso · porte (sugerido pelo plano). Cluster: VIP/balanceador, nomes no DNS ou /etc/hosts nome da máquina · porte do plano
4 Origem das imagens: registry, build ou bundle bundle se houver pacote em dist/, senão registry
5 Certificado inicial: autoassinado ou arquivos .crt/.key existentes autoassinado
6 Proxy de saída · diretórios (instalação, dados do Docker, backups) · fuso horário sem proxy · /opt/quantix, /var/lib/docker, /var/backups/quantix

As respostas ficam em .install/answers.yml (sem segredos) e viram o padrão da próxima execução.

Dimensionamento (primeira pergunta)

Ativo é o que a plataforma monitora. O administrador responde um ou mais tipos (Enter = 0; 25.000 e 25000 valem o mesmo):

Tipo Unidade O que conta
Máquinas virtuais VMs cada VM monitorada (vSphere, Nutanix/AHV); hosts e datastores entram junto
Armazenamento TB capacidade útil dos arrays de storage e NAS monitorados
Portas de SAN portas portas Fibre Channel dos switches/diretores SAN (Brocade, Cisco MDS)

O instalador calcula séries e pontos/dia (o mesmo cálculo da tela Administração › Plataforma, em backend/quantix/common/sizing.py) e mostra o ambiente recomendado: faixa, vCPUs, memória, armazenamento (com o tipo de disco), servidores, containers com réplicas e CPU/RAM por réplica e como alocar os recursos. Exemplo (25 mil VMs, 150 PB, 30 mil portas):

Ambiente recomendado: Grande — host único com perfil de escala
  Ativos (24 meses): 25.000 VMs · 150.000 TB · 30.000 portas
  Volume estimado: 2.879.875 séries · 1.186.524.000 pontos/dia · ClickHouse 5,05 TB com folga
  Faixa              large → porte do compose: large
  Servidores         1
  vCPUs              76
  Memória            248 GB
  Armazenamento      5,3 TB (NVMe)
  Containers         15 (réplicas somadas)
  Coletores remotos  3 (um por site/fabric)

  Containers
    container            réplicas  vCPU/réplica  RAM/réplica     disco  nó
    api                         2             8         8 GB         —  app  sem estado; escale por réplicas
    ingestor                    4             4         4 GB         —  app  consumidores do JetStream
    clickhouse                  1            32       128 GB    5,1 TB  app  séries temporais (SSD/NVMe)
    …
  Como alocar os recursos
    · ClickHouse em SSD/NVMe dedicado …
Faixa do plano Porte do compose Topologia sugerida
small (até ~0,12 × 10⁹ pontos/dia) small host único
medium (até ~0,45 × 10⁹) medium host único
large (até ~1,2 × 10⁹) large (docker-compose.scale.yml) host único
cluster (acima) large nos nós de aplicação cluster distribuído: ClickHouse em 2+ shards × 2 réplicas, Keeper em 3 nós, 2 nós de aplicação

O porte segue o plano; no host único ele ainda pode ser trocado na etapa 3. Para ver só o plano, sem instalar: ./install.sh plan (ou ./install.sh plan --json --vms 30000 --tb 150000 --san-ports 30000, que não exige Ansible e é usado pelo agente do host).

Cluster distribuído

Quando o plano indica cluster (ou o administrador escolhe a topologia cluster), a etapa 2 pergunta quantos nós de aplicação, quantos shards e réplicas de ClickHouse, e o nome e o IP de cada servidor (os nomes sugeridos vêm do plano: quantix-app1, quantix-ch-s1r1…). O primeiro nó de aplicação é o primário (PostgreSQL, NATS, coletor local e automação); o ClickHouse Keeper fica nos 3 primeiros nós ClickHouse. O acesso SSH (usuário com sudo, porta e chave) é o mesmo para todos os nós.

Na etapa 3 o instalador pergunta o IP (ou nome) do VIP/balanceador do nome público e se os nomes já existem no DNS. Ele confere a resolução a partir do controlador e mostra exatamente quais registros criar:

  ✖ quantix-ch-s1r1.empresa.local      esperado 10.10.0.31       resolve: não resolve
  ! Crie (ou corrija) estes registros A no DNS:
      quantix-app1.empresa.local.              IN A    10.10.0.21
      quantix-ch-s1r1.empresa.local.           IN A    10.10.0.31
      quantix.empresa.local.                   IN A    10.10.0.30
   › 1) conferir     conferir de novo (depois de criar os registros)
     2) hosts        usar /etc/hosts nos nós (o instalador grava em todos)
     3) continuar    seguir assim (o preflight confere de novo em cada nó)

Com hosts (dns_mode: hosts), o instalador grava as linhas IP nome em /etc/hosts de todos os nós e em extra_hosts dos containers; o nome público continua precisando existir no DNS dos usuários.

Antes de instalar, o preflight do cluster verifica cada nó: acesso SSH e sudo, sistema operacional, vCPUs/memória/disco frente ao que o plano pede para aquele nó, portas livres, firewall entre os nós (9000, 9009, 8123, 9181, 9234; 5432 e 4222 do primário para os secundários), latência (aviso acima de 2 ms), NTP, diferença de relógio e resolução dos nomes em cada nó. Detalhes, arquitetura e operação: Cluster distribuído.

Expandir uma instalação existente

./install.sh expand                                  # guiado (o servidor atual vira o nó primário)
./install.sh expand --answers cluster.yml --yes      # não interativo (usado pelo agente do host)
./install.sh expand --rollback                       # volta ao ClickHouse de nó único

O expand faz o backup completo, sobe os nós ClickHouse, copia o histórico do ClickHouse local para o cluster, troca a aplicação e confere /api/health; o volume antigo fica intacto para o rollback. Veja Cluster distribuído › Expansão.

Verificações (preflight)

Antes de alterar qualquer coisa, o instalador verifica o servidor e mostra o resultado:

Verificação Bloqueia quando
Sistema operacional e arquitetura não suportado
vCPUs, memória, disco livre no diretório do Docker abaixo do mínimo absoluto (4 vCPU, 16 GB, 80 GB). Abaixo do porte escolhido, apenas avisa
Portas 80 e 443 em uso por outro serviço
Docker Engine e Compose 2.24+ ausentes com docker_install: never
Acesso de saída (Docker, registro, PyPI, npm) o destino necessário para a origem escolhida não responde
Pacote offline arquivo não encontrado
Relógio (NTP), DNS do endereço, SELinux, instalação existente nunca (aviso/informação)

Para rodar só as verificações: ./install.sh preflight. Use --force apenas se souber o motivo da falha e aceitar o risco.

O que a instalação faz

  1. Instala o Docker Engine e o plugin Compose (repositório oficial ou espelho), se ainda não houver. Configura o daemon.json (rotação de logs, data-root), o proxy do daemon e os ajustes de kernel para o ClickHouse (vm.max_map_count, swappiness, THP em madvise, nofile).
  2. Copia os arquivos de implantação para /opt/quantix e gera o .env (0600) com segredos fortes, o perfil de recursos do porte e o token de instalação (QV_SETUP_TOKEN). Em execuções seguintes, os segredos existentes são preservados.
  3. Ajusta os limites de CPU dos containers ao total de vCPUs do servidor.
  4. Gera o certificado autoassinado (com o nome público, o nome da máquina e o IP) ou copia o fornecido.
  5. Obtém as imagens conforme a origem: docker compose pull, docker build no servidor, ou docker load do pacote offline. Depois confere se todas as imagens do compose estão presentes.
  6. Sobe a plataforma, aguarda /api/health e o HTTPS local e agenda o backup diário.
  7. Mostra o link do assistente:
──────────────────────────────────────────────────────────────────
  Quantix Vision AI 8.3.0 instalado em quantix01
──────────────────────────────────────────────────────────────────
  Abra no navegador para criar o administrador e concluir a configuração:

    https://quantix.empresa.com.br/setup#token=qvs_…

  Token de instalação: qvs_…

O token vai no fragmento (#token=), que o navegador não envia ao servidor nem grava em logs. Depois que o assistente é concluído, o token deixa de valer. Veja Assistente de primeira execução.

Origem das imagens

Origem Quando usar Requisito
registry há um registro com as imagens do Quantix (interno ou público) acesso ao registro; login opcional (QV_REGISTRY_PASSWORD)
build o servidor tem internet e você não usa registro acesso a Docker Hub, PyPI e npm; leva de 10 a 20 minutos
bundle servidor sem internet (comum em órgãos públicos e redes segregadas) o pacote gerado por ./install.sh bundle

Pacote offline

Numa máquina com Docker e internet:

./install.sh bundle                     # → dist/quantix-vision-ai-8.3.0-offline.tar

O pacote contém o código, o instalador, a documentação, as imagens (docker save de backend, web, PostgreSQL, ClickHouse, ClickHouse Keeper e NATS) e os pacotes do Ansible para controladores sem internet. No ambiente isolado:

tar -xf quantix-vision-ai-8.3.0-offline.tar && cd quantix-vision-ai-8.3.0
sudo ./install.sh                       # detecta dist/…-images.tar.gz e sugere "bundle"

O Docker precisa estar instalado no servidor ou disponível num espelho interno de pacotes (docker_repo_base_url).

Modo não interativo

Para automação, CI ou o agente de host:

./install.sh answers -o respostas.yml     # exemplo comentado
vi respostas.yml
./install.sh install --answers respostas.yml --yes
Chave Valores Padrão
target local, remote local
host, ssh_user, ssh_port, ssh_key servidor remoto —, —, 22, agente SSH
ssh_accept_new_host_key aceita a chave do host na primeira conexão true
public_url https://nome nome da máquina
size small, medium, large medium
clickhouse_cluster true com size: large false
image_source registry, build, bundle registry
registry, registry_login, registry_host, registry_user registro de imagens quantix, false
bundle_file caminho do …-images.tar.gz no controlador —
tls_mode, tls_cert, tls_key self-signed ou provided + arquivos PEM self-signed
https_proxy, http_proxy, no_proxy proxy de saída sem proxy
install_dir, docker_data_root, backup_dir, backup_retention_days diretórios e retenção /opt/quantix, /var/lib/docker, /var/backups/quantix, 14
docker_install auto (instala se faltar), always, never auto
docker_repo_base_url espelho dos pacotes do Docker https://download.docker.com/linux
timezone fuso dos containers America/Sao_Paulo
first_run_wizard false cria o admin com senha gerada no .env (sem assistente) true
assets {vms, tb, san_ports}: ativos previstos para 24 meses. Sem size no arquivo, o porte vem do plano 0 (não informado)
topology single (host único) ou cluster (vários servidores) single
cluster_nodes lista {name, ip, role, shard, replica, keeper} (role: app ou clickhouse); o 1º app é o primário; keeper: true em 3 nós ClickHouse —
cluster_public_vip IP (ou nome) do VIP/balanceador do nome público IP do nó primário
dns_mode dns (registros no DNS) ou hosts (o instalador grava /etc/hosts nos nós) dns

No cluster, ssh_user, ssh_key e ssh_port valem para todos os nós (target/host são ignorados). Exemplo:

topology: cluster
public_url: https://quantix.empresa.com.br
assets: {vms: 50000, tb: 300000, san_ports: 60000}
ssh_user: ansible
ssh_key: ~/.ssh/id_ed25519
dns_mode: dns
cluster_public_vip: 10.10.0.30
cluster_nodes:
  - {name: quantix-app1.empresa.com.br, ip: 10.10.0.21, role: app}
  - {name: quantix-app2.empresa.com.br, ip: 10.10.0.22, role: app}
  - {name: quantix-ch-s1r1.empresa.com.br, ip: 10.10.0.31, role: clickhouse, shard: 1, replica: 1, keeper: true}
  - {name: quantix-ch-s1r2.empresa.com.br, ip: 10.10.0.32, role: clickhouse, shard: 1, replica: 2, keeper: true}
  - {name: quantix-ch-s2r1.empresa.com.br, ip: 10.10.0.33, role: clickhouse, shard: 2, replica: 1, keeper: true}
  - {name: quantix-ch-s2r2.empresa.com.br, ip: 10.10.0.34, role: clickhouse, shard: 2, replica: 2}

Segredos nunca vão para o arquivo; use variáveis de ambiente: QV_BECOME_PASSWORD (sudo), QV_SSH_PASSWORD (SSH por senha, exige sshpass) e QV_REGISTRY_PASSWORD. Variáveis avançadas do Ansible podem ser passadas em JSON por QV_ANSIBLE_EXTRA_VARS, por exemplo QV_ANSIBLE_EXTRA_VARS='{"docker_manage": false}' quando o Docker é administrado por outra equipe.

Comandos

Comando O que faz
./install.sh ou ./install.sh install instala ou reaplica a configuração (idempotente); começa pelo dimensionamento
./install.sh plan só o dimensionamento (--json, --vms, --tb, --san-ports, --answers); não exige Ansible
./install.sh expand converte a instalação de host único em cluster distribuído; --rollback desfaz
./install.sh agent instala/atualiza o agente do host (deploy/ansible/agent.yml, também executado no fim do site.yml)
./install.sh preflight só as verificações (no cluster, de todos os nós). Com --answers, verifica outra configuração sem alterar a instalação registrada
./install.sh status containers, /api/health e HTTPS local
./install.sh setup-link mostra de novo o link e o token do assistente (enquanto pendente)
./install.sh upgrade atualiza para a versão do pacote, com backup antes (Atualização)
./install.sh bundle gera o pacote offline
./install.sh answers -o arquivo grava um arquivo de respostas de exemplo

Opções: --answers/-a, --yes/-y, --force, --ask-become-pass/-K, --verbose/-v, --no-color, --json, --vms, --tb, --san-ports (plan) e --rollback (expand). Cada execução grava o log completo em .install/logs/.

Arquivos

Onde Conteúdo
.install/answers.yml (controlador) respostas, sem segredos
.install/logs/ log completo de cada execução
.install/cluster-preflight.json, .install/answers-expand.yml relatório do preflight do cluster; respostas do último expand (0600)
.install/preflight.json, .install/result.json resultado das verificações e da instalação (0600; o resultado contém o token enquanto o assistente estiver pendente)
deploy/ansible/inventory/.installer-hosts.yml inventário gerado
/opt/quantix/.env (servidor) segredos, incluindo QV_MASTER_KEY e QV_SETUP_TOKEN (0600). Guarde uma cópia fora do servidor
/opt/quantix/deploy/certs/ certificado do instalador. O enviado pela GUI fica no volume quantix-tls