Pular para conteúdo

Assistente de primeira execução

Em instalações feitas pelo instalador, a plataforma sobe sem nenhum usuário. O primeiro acesso a qualquer página leva a /setup, onde o assistente cria o administrador e confirma os dados básicos. Ele não exige editar arquivos no servidor e pode ser retomado de qualquer navegador: o progresso fica gravado no PostgreSQL.

Etapa Obrigatória O que define
1. Token de instalação sim prova que quem está configurando executou o instalador
2. Administrador sim primeira conta local, com acesso total
3. Organização sim nome da instalação, endereço público, fuso horário, idioma
4. Certificado HTTPS não certificado da CA da empresa (PEM ou PFX)
5. Diretório (AD/LDAP) não login corporativo e grupos → papéis
6. E-mail não servidor SMTP para alertas e relatórios
7. Revisão sim confere tudo e conclui

Token de instalação

1. Token de instalação

O link exibido pelo instalador já traz o token (https://<servidor>/setup#token=qvs_…). Se abrir /setup sem ele, cole o token mostrado no fim do ./install.sh. Para vê-lo de novo:

sudo ./install.sh setup-link            # no controlador da instalação
sudo grep QV_SETUP_TOKEN /opt/quantix/.env   # no servidor

Por segurança, dez tentativas com token errado bloqueiam o endereço de origem por 15 minutos (o endereço considerado é o que o nginx recebeu, não um cabeçalho enviado pelo cliente). O token só vale enquanto a configuração está pendente, e as etapas são gravadas uma de cada vez (bloqueio de linha no PostgreSQL), então duas abas abertas não sobrescrevem uma à outra.

2. Administrador

Administrador

A conta criada aqui é local e tem acesso total. Ela continua funcionando se o diretório corporativo ficar fora do ar, por isso guarde a senha num cofre. A senha segue a política de Configurações › Segurança: tamanho mínimo (padrão 12), letras maiúsculas e minúsculas, números, e não pode conter o nome de usuário. Os requisitos ficam verdes à medida que são atendidos.

3. Organização

Organização

  • Nome da instalação: aparece no login, nos e-mails e nos relatórios.
  • Endereço de acesso: a URL HTTPS pública. É usada em links de alertas, no registro de coletores remotos e para conferir se o certificado cobre o nome.
  • Fuso horário e idioma padrão.

Os valores podem ser alterados depois em Administração › Configurações › Geral.

4. Certificado HTTPS

Certificado

O instalador cria um certificado autoassinado, e por isso o navegador mostra um alerta. Envie o certificado emitido pela CA da empresa em um destes formatos:

  • PEM: certificado com a cadeia intermediária (.crt/.pem) e a chave privada (.key), opcionalmente protegida por senha;
  • PFX/P12: exportado do Windows/AD CS com a chave e a cadeia.

Clique em Validar para conferir antes de aplicar. A plataforma verifica:

Item Resultado
chave corresponde ao certificado erro se não corresponder
validade erro se expirado ou ainda não válido; aviso se faltar menos de 30 dias
tipo e tamanho da chave RSA ≥ 2048 ou ECDSA P-256/P-384 (Ed25519 é recusado: os navegadores não aceitam)
nome do endereço público coberto (SAN, incluindo curinga) aviso se não cobrir
cadeia intermediária aviso se faltar; a cadeia é reordenada automaticamente

Aplicar certificado grava o par no volume quantix-tls. O container web detecta a troca e recarrega o nginx em até 15 segundos, sem interromper conexões. Se o nginx recusar o par, o certificado anterior é mantido e o erro aparece no log do web. Para trocar depois (renovação anual, por exemplo), use Administração › Sistema › Certificado HTTPS.

Em Kubernetes, o certificado é o Secret do Ingress/Helm e esta etapa apenas informa isso.

5. Diretório (AD/LDAP)

Diretório

Configura o login com contas corporativas (Active Directory, OpenLDAP ou FreeIPA/IdM):

  • Servidores: um ou mais, separados por vírgula (failover automático). LDAPS (636) é o padrão. Para CA interna, cole o certificado da CA.
  • Base DN e conta de serviço (bind DN somente leitura).
  • Grupos → papéis: grupos (DN ou nome) para Administradores, Operadores, Analistas e Somente leitura. Grupos aninhados são considerados. Quem não está em nenhum grupo recebe o papel padrão (ou nenhum acesso).
  • Testar conexão: faz o bind e, se informado, procura um usuário de teste e lista os grupos.

Mapeamentos por tenant, filtros e atributos personalizados ficam em Diretórios (LDAP/AD).

6. E-mail

Servidor SMTP (porta, STARTTLS, usuário, senha e remetente), com envio de teste. Teams, Slack, syslog, ServiceNow e webhooks são configurados em Alertas.

7. Revisão e conclusão

Revisão

A revisão mostra o resumo de cada etapa, com Editar para voltar a ela. Etapas opcionais puladas aparecem como "configurar depois". Ao concluir:

  • o estado passa a concluído, as rotas /api/v1/setup/* passam a responder 410 e o token deixa de valer;
  • a conclusão é registrada na auditoria (setup_completed), assim como cada etapa (setup_admin, setup_organization, setup_tls, setup_directory, setup_smtp);
  • você entra automaticamente como o administrador criado.

Pronto

O próximo passo sugerido é Adicionar o primeiro dispositivo (ver Dispositivos).

Instalações sem assistente

O assistente não aparece quando o .env define QV_ADMIN_PASSWORD (laboratório, make gen-env, Helm com senha definida) ou quando a instalação já tinha usuários antes da versão com o assistente. Nesses casos o administrador é criado no boot, como antes.

API

Rota Autenticação Uso
GET /api/v1/setup/status pública indica se o assistente é necessário e quais etapas foram feitas (sem nomes, e-mails ou servidores)
GET /api/v1/setup/state X-Setup-Token estado completo: resumo de cada etapa e valores sugeridos
POST /api/v1/setup/verify X-Setup-Token confere o token
POST /api/v1/setup/admin · organization · tls · directory · smtp X-Setup-Token grava cada etapa
POST /api/v1/setup/directory/test · smtp/test X-Setup-Token testes sem gravar
POST /api/v1/setup/{tls,directory,smtp}/skip X-Setup-Token pula etapa opcional
POST /api/v1/setup/complete X-Setup-Token conclui e devolve a sessão do administrador
GET/POST /api/v1/admin/tls JWT + settings.manage consulta e troca o certificado depois da instalação