Vidocq Documentation

Cette page couvre les usages avancés de Vidocq Runtime au-delà du Hello world : packaging via le vidocq-runtime-maven-plugin (jlink, jpackage, Docker), configuration via https://microprofile.io/specifications/microprofile-config/, observabilité (https://microprofile.io/specifications/microprofile-health/, https://microprofile.io/specifications/microprofile-metrics/, https://microprofile.io/specifications/microprofile-open-api/), profils, et préparation AOT.

Packaging avec vidocq-runtime-maven-plugin

Le plugin Maven expose trois cibles de packaging. Voir la fiche dédiée pour l’inventaire complet et le détail JLINK.md interne au repo.

Goal Sortie Démarrage typique

vidocq:jlink

target/dist/ (binaire + runtime Java embarqué, ~40 Mo)

~4 s

vidocq:jpackage

target/installer/<name>.app ou .exe/.msi/.deb/.rpm

~1 s (CDS)

vidocq:docker

target/Dockerfile distroless basé sur distroless/base-debian12:nonroot

~50 Mo image

Quick start (depuis vidocq-runtime-cassini-rest-example) :

cd vidocq-runtime-examples/vidocq-runtime-cassini-rest-example
./mvnw -ntp package -DskipTests
./target/dist/bin/todo-app

Configuration MicroProfile

Vidocq Runtime implémente https://microprofile.io/specifications/microprofile-config/. Hiérarchie des sources, du plus prioritaire au moins prioritaire :

Ordinal Source Description

400

SystemPropertiesConfigSource

-Dkey=value

300

EnvConfigSource

Variables d’environnement (KEY_NAME)

250

ExternalFileConfigSource

${java.home}/conf/vidocq.properties (image jlink)

100

PropertiesFileConfigSource

vidocq.properties du classpath

ExternalFileConfigSource permet de surcharger un binaire jlink/jpackage déployé sans rebuilder, simplement en éditant le fichier conf/vidocq.properties à côté du launcher. Une ligne de log au boot trace le chargement effectif.

Health

@Liveness
@ApplicationScoped
public class DatabaseHealth implements HealthCheck {
    @Inject DataSource ds;

    @Override
    public HealthCheckResponse call() {
        try (Connection c = ds.getConnection()) {
            return HealthCheckResponse.up("database");
        } catch (SQLException e) {
            return HealthCheckResponse.down("database");
        }
    }
}

Endpoints exposés : /q/health, /q/health/live, /q/health/ready, /q/health/started (jalon en cours, voir TCK).

Metrics

Implémentation https://microprofile.io/specifications/microprofile-metrics/ en cours. Les compteurs et histogrammes seront enregistrés au build time par l’extension vidocq-runtime-metrics-extension. Endpoint Prometheus /q/metrics.

OpenAPI

L’extension vidocq-runtime-openapi-extension (jalon courant) génère le document OpenAPI à la compilation à partir des annotations Jakarta REST + MicroProfile OpenAPI. Endpoint /q/openapi.

Profils

Convention MicroProfile : préfixer une clé par %<profil>. pour la scoper.

vidocq.http.port=8080
%dev.vidocq.http.port=8081
%prod.vidocq.http.port=80

Activation via -Dvidocq.profile=dev ou la variable VIDOCQ_PROFILE.

Déploiement Docker

Image distroless minimale produite par vidocq:docker :

./mvnw -ntp package -Dvidocq.docker.build=true
docker run --rm -p 8080:8080 \
    -e VIDOCQ_CONFIG_DIR=/etc/myapp \
    -v $(pwd)/conf:/etc/myapp:ro \
    example/my-app:1.0.0

Le base image distroless/base-debian12:nonroot n’a ni shell ni package manager — surface d’attaque réduite. L’utilisateur nonroot (UID 65532) est imposé.

AOT — GraalVM et Leyden

  • Leyden CDS — supporté de série. La génération statique Class-File API produit un bytecode parfaitement archivable.

  • GraalVM native-image — la stratégie zéro-réflexion + zéro-proxy de Vidocq Runtime minimise les reachability-metadata. Voir vidocq/JLINK.md pour les pré-requis runtime (logging.properties, JPMS nommés, records sérialisés).

Pour aller plus loin