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 |

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¶

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¶

- 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¶

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)¶

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¶

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.

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 |