AutoflowTrilha 08 · Integrações e implantação
Infraestrutura e implantação
Você não precisa ser engenheiro de infraestrutura, mas precisa saber o que roda, onde, o que cada peça faz e o que perguntar à TI do cliente — principalmente em órgãos públicos, que muitas vezes exigem hospedagem própria. Esta lição é o roteiro de um ambiente novo.
As peças
Clique em cada peça para ver o que faz e por quê.
| Container | Função | Exposição |
|---|---|---|
postgres (16) |
Dados do Autoflow + bancos do Camunda e do Keycloak | só local |
minio |
Arquivos (documentos, imagens) | só local; servidos pela API |
migrate |
Roda as migrações do banco (sob demanda) | — |
api (NestJS) |
Cérebro: APIs interna, pública, portal e plataforma + filas | via nginx |
web |
App da empresa | via nginx |
super |
Console de suporte | host próprio + allowlist de IP |
portal |
Portal externo | host próprio |
camunda (7.24) |
Motor BPMN/DMN | nunca exposto |
keycloak (26) |
Identidade; realms do produto e do portal | via nginx em /auth |
Todos os containers escutam só em 127.0.0.1; o nginx do servidor termina o HTTPS e encaminha.
O motor não sabe nada sobre clientes, permissões ou unidades — quem garante isso é a API. Se o Camunda fosse acessível, alguém poderia concluir tarefas ou ler variáveis de qualquer cliente. A regra “o navegador nunca fala com o motor” é a base da segurança multiempresa.
Três endereços (hosts)
- Produto (ex.:
autoflow.cliente.gov.br): app da empresa, API e Keycloak em/auth. - Suporte (ex.:
admflow.…): Console Super, com allowlist de IP/VPN; só repassa a API de plataforma. No host do produto, a API de plataforma responde 404. - Portal (ex.:
portalflow.…): portal do participante externo.
Passo a passo de um ambiente novo
- DNS e TLS para os três hosts.
- Variáveis: copiar o modelo de produção para
.env.prode preencher todos os segredos (lista abaixo). - Gerar os realms do Keycloak de produção (sem usuários de demonstração, com as URLs reais, secret e SMTP). O import só acontece se o realm ainda não existe — depois, mudanças vão pelo console do Keycloak ou scripts.
- Subir a base: build das imagens; subir postgres, minio, camunda, keycloak; rodar as migrações; subir api, web, super, portal.
- Aplicar o tema do Keycloak (rodar após todo deploy; é idempotente).
- Configurar o nginx dos três hosts (com allowlist no host de suporte), testar e recarregar.
- Smoke tests (checklist abaixo).
- Criar o primeiro operador de plataforma no Keycloak: grupo
/Plataforma, papelplatform-operator, OTP configurado. - Provisionar cada cliente pelo Console Super (trilha 06).
O README de deploy ainda descreve criar o primeiro admin do cliente pelo console do Keycloak ou por SQL — isso foi substituído pelo provisionamento no Console Super. E o guia do despachante cita um script de seed que foi removido; o conteúdo vem do pacote do segmento Concessionária.
Variáveis que você precisa conhecer
| Grupo | Variáveis | Observação |
|---|---|---|
| App | APP_PUBLIC_URL, DATABASE_*, DATABASE_APP_PASSWORD, MINIO_* |
A role do app no banco não ignora RLS |
| Keycloak | KC_HOSTNAME, KEYCLOAK_ISSUER, KEYCLOAK_JWKS_URL, KEYCLOAK_ADMIN_* |
Use JWKS pela rede interna |
| Camunda | CAMUNDA_USER, CAMUNDA_PASSWORD |
O exemplo vem com demo/demo: troque |
| Integrações | INTEGRATIONS_KEK_*, INTEGRATIONS_API_KEY_PEPPER, INTEGRATIONS_PUBLIC_API_URL |
KEK também cifra a chave da IA |
| E-mail e push | SMTP_*, MAIL_FROM, PUSH_VAPID_* |
Sem SMTP não há convites; trocar VAPID invalida inscrições de push |
| Super e portal | SUPER_PUBLIC_URL, PLATFORM_READ_ONLY, PORTAL_PUBLIC_URL, KEYCLOAK_EXTERNAL_* |
— |
| Assistente | ASSISTANT_* |
Tempos e cotas |
| Proibida em produção | ORGANIZATION_BOOTSTRAP_ROUTE |
A API se recusa a subir com ela em produção |
Smoke tests
Backup
não há no repositório Não existe script nem procedimento de backup versionado. A única menção é um pré-requisito de “faça backup do Postgres e do MinIO” num roteiro de limpeza. Recomendação (a combinar com a TI do cliente):
pg_dumpdiário dos três bancos: aplicação,camundaekeycloak— eles precisam ser consistentes entre si;- cópia do volume/bucket do MinIO;
- guardar o
.env.prode os realms gerados em cofre; - testar a restauração pelo menos uma vez antes do go-live.
Restaurar só o banco da aplicação sem o do Camunda (ou vice-versa) gera processos “fantasmas” e tarefas órfãs. Backup e restauração são sempre do conjunto.
Segurança em uma página
- Isolamento entre clientes: cada tabela tem
tenant_ide RLS no PostgreSQL; a aplicação usa uma role sem permissão de ignorar o RLS. Matriz/filial são filtradas na aplicação. - Identidades separadas: usuários internos (realm do produto), suporte (client próprio, sem tenant, com MFA), externos (realm do portal), sistemas (API key ou token delegado). Testes automatizados garantem que um token de um “mundo” não funciona no outro.
- Segredos de integrações e da IA são cifrados (AES-256-GCM) e nunca exibidos de novo; API keys guardadas só como hash.
- Webhooks só para HTTPS e sem IP privado (anti-SSRF).
- LGPD: mascaramento no suporte, revelação auditada, variáveis sensíveis fora de webhooks/métricas, encerramento de conta no portal, retenções definidas.
- observação O download de documentos autentica com o token na URL (registrado na auditoria funcional) — relevante se o cliente fizer análise de segurança.
Onde os dados ficam hospedados? Quem tem acesso administrativo e como é registrado? Há MFA? Qual a política de backup e o tempo de restauração? Como é o isolamento entre órgãos? Como se exerce o direito de eliminação? Prepare as respostas com base nesta lição e na de Suporte, e valide os pontos de backup e logs (sem agregação hoje) antes de assinar SLA.
Problemas típicos
| Sintoma | Causa provável |
|---|---|
| Login funciona, mas tudo dá 401 depois | API buscando as chaves do Keycloak pelo endereço público (hairpin NAT). Use KEYCLOAK_JWKS_URL interno |
| Tela em branco no login | CSP bloqueando o silent-check-sso |
| Console Super cai em “Acesso restrito” | Conta sem papel de plataforma, conta com tenant, ou vhost sem repassar a API de plataforma |
| Convites não chegam | SMTP |
| Push parou para todos | Chaves VAPID trocadas |
Resumo
- Nove peças: postgres, minio, migrate, api, web, super, portal, camunda, keycloak; só a API fala com o motor.
- Três hosts: produto, suporte (com allowlist) e portal.
- Ordem: DNS/TLS → variáveis → realms → base + migrações → apps → tema → nginx → smoke → operador → clientes.
- Backup não está automatizado no repositório: combine e teste restauração dos três bancos + MinIO.