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¶
- 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 emmadvise,nofile). - Copia os arquivos de implantação para
/opt/quantixe 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. - Ajusta os limites de CPU dos containers ao total de vCPUs do servidor.
- Gera o certificado autoassinado (com o nome público, o nome da máquina e o IP) ou copia o fornecido.
- Obtém as imagens conforme a origem:
docker compose pull,docker buildno servidor, oudocker loaddo pacote offline. Depois confere se todas as imagens do compose estão presentes. - Sobe a plataforma, aguarda
/api/healthe o HTTPS local e agenda o backup diário. - 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:
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 |