Vidocq Documentation

This page covers Vidocq Runtime usage beyond the hello world: packaging via the vidocq-runtime-maven-plugin (jlink, jpackage, Docker), configuration via https://microprofile.io/specifications/microprofile-config/, observability (https://microprofile.io/specifications/microprofile-health/, https://microprofile.io/specifications/microprofile-metrics/, https://microprofile.io/specifications/microprofile-open-api/), profiles, and AOT preparation.

Packaging with vidocq-runtime-maven-plugin

The Maven plugin exposes three packaging targets. See the dedicated page for the full inventory and the internal JLINK.md details.

Goal Output Typical startup

vidocq:jlink

target/dist/ (binary + embedded Java runtime, ~40 MB)

~4 s

vidocq:jpackage

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

~1 s (CDS)

vidocq:docker

target/Dockerfile distroless based on distroless/base-debian12:nonroot

~50 MB image

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

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

MicroProfile configuration

Vidocq Runtime implements https://microprofile.io/specifications/microprofile-config/. Source hierarchy, highest to lowest priority:

Ordinal Source Description

400

SystemPropertiesConfigSource

-Dkey=value

300

EnvConfigSource

Environment variables (KEY_NAME)

250

ExternalFileConfigSource

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

100

PropertiesFileConfigSource

classpath vidocq.properties

ExternalFileConfigSource lets you override a deployed jlink/jpackage binary without rebuilding, simply by editing the conf/vidocq.properties file next to the launcher. A boot log line traces the effective load.

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 exposed: /q/health, /q/health/live, /q/health/ready, /q/health/started (current milestone, see TCK).

Metrics

https://microprofile.io/specifications/microprofile-metrics/ implementation in progress. Counters and histograms will be registered at build time by the vidocq-runtime-metrics-extension extension. Prometheus endpoint /q/metrics.

OpenAPI

The vidocq-runtime-openapi-extension extension (current milestone) generates the OpenAPI document at compile time from Jakarta REST + MicroProfile OpenAPI annotations. Endpoint /q/openapi.

Profiles

MicroProfile convention: prefix a key with %<profile>. to scope it.

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

Activate via -Dvidocq.profile=dev or the VIDOCQ_PROFILE environment variable.

Docker deployment

Minimal distroless image produced by 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

The distroless/base-debian12:nonroot base image has no shell, no package manager — minimal attack surface. The nonroot user (UID 65532) is enforced.

AOT — GraalVM and Leyden

  • Leyden CDS — supported out of the box. Static Class-File API codegen produces bytecode that archives perfectly.

  • GraalVM native-image — Vidocq Runtime’s zero-reflection + zero-proxy strategy minimises reachability-metadata. See vidocq/JLINK.md for runtime prerequisites (logging.properties, named JPMS modules, serialised records).

Next steps