Como rodar localmente

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

Build e testes estão em Como buildar e testar; a organização do código, no guia do código.

Pré-requisitos

• JDK 25 no JAVA_HOME. O plugin io.micronaut.application 5 só configura numa JVM 25, então o toolchain do build não basta: o Gradle precisa rodar nela. A versão é a do docs/app.json (toolchain.java), a mesma da CI — ver a decisão 0009.
• Docker rodando: o run sobe o Postgres de dev, e os testes usam Testcontainers.
• Build pelo wrapper (./gradlew; no Windows, .\gradlew.bat) — nunca Maven.

Subir o app

./gradlew genDevKeys   # uma vez: par RSA de dev em dev-keys/ (gitignored)
./gradlew run          # sobe o Postgres 18 e o app em http://localhost:8080

O run chama antes a task subirInfraDev, que sobe o Postgres do docker-compose.dev.yml na porta 5433, com as credenciais que o application.yml usa por padrão, e espera o banco ficar saudável. Para parar o banco: ./gradlew pararInfraDev.

Quem já tem um Postgres próprio exporta DATASOURCES_DEFAULT_URL (e DB_USER/DB_PASSWORD): a subida do Docker é pulada. As demais variáveis de ambiente estão na tabela do README do repo; para o login Firebase local, defina CENTRAL_FIREBASE_PROJECT_ID.

Chaves e tokens de dev

Task	O que gera
genDevKeys	par RSA de dev em dev-keys/, usado pelo profile dev
genDevAdminToken	JWT xadm_admin de 365 dias assinado com a chave de dev, para o auth.token do integrador.properties
genAuthTestKeys	par RSA dos testes de integração; o test já depende dela

./gradlew tasks --group development lista as tasks de dev.

Rodar a imagem native

docker build -f Dockerfile.native -t central-backend:native-test .

É o mesmo Dockerfile.native que a CI builda e publica. Para o loop rápido só do binário, sem imagem: ./gradlew nativeCompile -PnativeQuick --no-configuration-cache (GraalVM 25 no JAVA_HOME; o -PnativeQuick troca o -Os de produção pelo -Ob, que compila mais rápido). O gate de adoção native é o e2e do workspace em etc/tests/native/e2e-central/ (scripts/run-native.ps1 -Rebuild), que sobe a imagem e valida login → JWT → assinatura, Firebase, presign S3 e o locale pt-BR do alerta de silêncio — ver a decisão 0018.

Testar uma lib da casa antes do release

O build.gradle.kts traz o mavenLocal() depois do registro e só para o grupo br.com.xadm, como manda Bibliotecas da casa. A versão publicada sempre sai do registro; o ~/.m2 só preenche o número que ainda não saiu. Para testar o app contra uma mudança da xadm-commons, a lib sobe o número do módulo e publica local (publishToMavenLocal), e o app declara esse número novo — republicar local um número que já está no registro não chega ao app.

./gradlew check              # a versão nova vem do ~/.m2
./gradlew --offline check    # com o registro fora do ar: o Gradle pula o registro e lê o ~/.m2 e o cache

A CI só fica verde depois que a versão sai no registro: o runner do pipeline.yml não tem ~/.m2, e a /xadm-release recusa dependência da casa que não está no registro.