Pular para conteúdo

0033 — Server Micronaut: native por padrão, jar declarado com motivo

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-12 · Decidido em: 2026-09-12

Substitui a 0022 só na topologia (quem builda, onde, e como o deploy é disparado). O resto da 0022 — elegibilidade, GraalVM CE, a troca de biblioteca de XLSX, o nome do binário — segue valendo.

Contexto

A 0022 fez do binário native o alvo de deploy do server Micronaut elegível, com a JVM como exceção declarada. Desde então três coisas mudaram por baixo dela: o jar também saiu do host de produção, o CI virou um pipeline.yml único (0027) e o gatilho de deploy passou a ser o control-plane (0026). A topologia que a 0022 descreve — um workflow de build próprio e uma ponte SSH na VM — não existe mais.

E a regra precisava ficar clara nos dois sentidos. "Native é o alvo" foi lido como "só native", o que não é verdade: há app com bloqueio de native medido, e há host de runtime em que o binário não roda. A casa quer native por padrão sem proibir a JVM.

Decisão

O server Micronaut declara build.targets: ["native"]. O jar entra no build.targets só com motivo declarado.

  • Motivos que valem para declarar jar: (a) bloqueio de native registrado em ADR do próprio app — hoje o integrador-server, que roda só jar por bloqueios medidos (locale, FCM, Jackson no upload, falta de e2e native); (b) host de runtime sem a arquitetura do binário native (ARM).
  • O app é native se e só se o build.targets contém native. Não há outro discriminador: o validador, as guardas do pipeline.yml e o e2e leem o mesmo campo.
  • Quem builda: o job build_<alvo> do pipeline.yml, num runner fora do host de produção. A norma fixa o princípio, não o fornecedor do runner. O deploy é disparado pelo control-plane e o Coolify só puxa a imagem (Build Pack Docker Image).
  • O repo carrega os dois Dockerfiles: Dockerfile.native (o padrão) e Dockerfile JVM (o fallback), com a guarda de paridade entre eles no pipeline.yml.
  • Fallback JVM: os recursos *-jar-pull ficam parados no Coolify. Religar a perna JVM exige release com jar no build.targets, isto é, imagem nova; nunca se religa o recurso parado com a imagem velha.

Alternativas descartadas

  • Só native. Ignora bloqueio medido e host ARM; o app bloqueado ficaria sem caminho conforme.
  • Jar por padrão, native opt-in. Devolve o custo que a 0022 existia para cortar: RSS alto, imagem grande, pico de build.
  • Jar e native no ar ao mesmo tempo, atrás do mesmo domínio. A medição por flavor do /health deu todo o tráfego no native; dois recursos no mesmo domínio ficam só para a troca blue-green, não como regime.

Consequências

  • O templates/pipeline.yml traz o native ativo e o jar comentado com o rótulo "jar declarado com motivo: descomente e ponha jar no build.targets".
  • O mapa de alvos da /xadm-release segue o campo: src/** builda os alvos do build.targets, Dockerfile.native só o native, Dockerfile só o jar.
  • Site de recuperação de desastre é projeto de infraestrutura, fora desta decisão; se ele for ARM, o jar continua sendo o artefato de lá, pelo motivo (b).
  • Receita operável em java-micronaut e em deploy.