Pular para conteúdo

Produção com Docker Compose

Prefira o instalador

./install.sh executa estes passos com verificações, gera o .env sem edição manual e deixa a criação do administrador para o assistente de primeira execução. Veja Instalador. Esta página descreve o caminho manual.

Host único

git clone … quantix-vision-ai && cd quantix-vision-ai
make gen-env          # gera .env a partir de .env.example (segredos fortes; preserva existentes)
vi .env               # QV_PUBLIC_URL, QV_REGISTRY/QV_VERSION, proxy, limites de recursos
make certs            # certificado autoassinado em deploy/certs (ou copie tls.crt / tls.key)
make build            # ou: make pull (registro interno)
make up               # sobe e aguarda /api/health

Acesse https://<servidor>/ com admin e a senha QV_ADMIN_PASSWORD do .env (se estiver vazia, use make admin-password). Na primeira vez, defina Configurações › Geral › URL pública.

Serviços (docker-compose.yml): postgres, clickhouse, nats, api (4 workers), ingestor (2 réplicas), engine, collector (coletor local), automation e web (único que publica portas: 443 e 80). Bancos e barramento ficam na rede internal (sem rota externa). api, engine, collector, automation e web também participam da rede egress.

Guarde o .env e a QV_MASTER_KEY

O .env contém todos os segredos e não entra no backup. Sem a mesma chave mestra, as credenciais de dispositivos não podem ser decifradas após uma restauração.

Ambiente grande

make up SCALE=1      # docker-compose.yml + docker-compose.scale.yml

O override aplica PostgreSQL com 4 GB de shared_buffers e 500 conexões, ClickHouse com 32 vCPU e 128 GB, ingestor ×4, engine com 8 vCPU/16 GB, API com 8 workers, coletor com concorrência 64 e pool de conexões 15. Coletores adicionais no mesmo host: --profile multi-collector (collector-2, collector-3), cada um com token próprio emitido na GUI (QV_COLLECTOR_TOKEN_2/_3).

ClickHouse em cluster: make up CLUSTER=1 (detalhes). Ambos combinados: make up SCALE=1 CLUSTER=1.

Variáveis principais do .env

Todas estão documentadas em .env.example e na referência. As que você normalmente ajusta:

Variável Uso
QV_PUBLIC_URL URL pública (coletores remotos, automação)
QV_REGISTRY, QV_VERSION imagens da plataforma
QV_HTTPS_PORT, QV_HTTP_PORT, QV_*_BIND, QV_CERTS_DIR publicação do nginx
QV_API_WORKERS, QV_INGESTOR_REPLICAS, QV_PG_POOL_SIZE escala dos serviços
*_CPUS, *_MEMORY, PG_* limites de cgroup e tuning do PostgreSQL
QV_HTTPS_PROXY, QV_NO_PROXY proxy de saída
QV_LOG_LEVEL, QV_LOG_JSON, QV_LOG_MAX_SIZE, QV_LOG_MAX_FILE logs

Conexões PostgreSQL: cada processo abre até 2 × QV_PG_POOL_SIZE. Garanta que (QV_API_WORKERS + réplicas de ingestor + engine + automação) × 2 × QV_PG_POOL_SIZE seja menor que PG_MAX_CONNECTIONS. Com o padrão: (4 + 2 + 1 + 1) × 2 × 10 = 160 < 300.

Operação do dia a dia (Makefile)

Alvo Ação
make ps / make logs S=api estado e logs (todos ou de um serviço)
make restart reinicia api, ingestor, engine, collector, automation, web
make down para e remove containers (volumes preservados)
make backup / make restore FROM=… backup e restauração
make config mostra o compose final
make lint valida compose, Ansible, Helm e Dockerfiles

Documentação embutida

make build-web inclui docs/site (saída de cd docs && mkdocs build --strict) na imagem web, servida em https://<servidor>/docs/. Rode python docs/gen_reference.py && python docs/gen_api.py antes, para atualizar as páginas geradas do código.