Vidocq Documentation

vidocq-runtime-maven-plugin is the Maven plugin that turns an application into a deployable standalone binary. It exposes four goals: build, jlink, jpackage, docker. Also see vidocq/JLINK.md for internal details.

Coordinates

Artefact

io.vidocq.runtime:vidocq-runtime-maven-plugin:0.1.0-SNAPSHOT

JPMS module

io.vidocq.runtime.maven

Goals

Goal Role

vidocq:build

Runs the topological @BuildStep graph, generates Class-File API classes, produces the runner JAR and extensions.list index.

vidocq:jlink

Standalone Java image (target/dist/) with bin/<launcher> binary — no java required on target.

vidocq:jpackage

Native OS bundle (.app macOS, .exe/.msi Windows, .deb/.rpm Linux) or cross-platform app-image.

vidocq:docker

Generates target/Dockerfile distroless based on distroless/base-debian12:nonroot. Optional build via vidocq.docker.build=true.

 
<plugin>
    <groupId>io.vidocq.runtime</groupId>
    <artifactId>vidocq-runtime-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>jlink</id>
            <goals><goal>jlink</goal></goals>
            <configuration>
                <mainModule>com.example.myapp</mainModule>
                <mainClass>com.example.myapp.MainApp</mainClass>
                <launcher>my-app</launcher>
                <distDir>${project.build.directory}/dist</distDir>
                <stripDebug>true</stripDebug>
                <compress>zip-6</compress>
                <includeResources>
                    <param>vidocq.properties</param>
                    <param>logging.properties</param>
                </includeResources>
            </configuration>
        </execution>
    </executions>
</plugin>

Typical output:

target/
├── dist/
│   ├── bin/my-app                  # binary launcher
│   ├── conf/                       # overridable config (ExternalFileConfigSource)
│   │   ├── vidocq.properties
│   │   └── logging.properties
│   ├── lib/                        # app + JDK JPMS modules
│   ├── legal/
│   └── release
├── installer/                      # if jpackage is enabled
│   └── my-app.app/
└── Dockerfile                      # if docker is enabled

vidocq:jpackage goal

Reuses the jlink image. Default type: app-image (cross-platform). On macOS, .app. On Windows, .exe or .msi. On Linux, .deb or .rpm.

See vidocq/JLINK.md §3 for the exhaustive parameter list.

vidocq:docker goal

Generates a distroless Dockerfile. Why distroless/base-debian12:nonroot?

  • No shell, no package manager — minimal attack surface.

  • Enforced nonroot user (UID 65532).

  • Compatible with the strictest image policies.

./mvnw -ntp package -Dvidocq.docker.build=true
docker run --rm -p 8080:8080 example/my-app:1.0.0

# With external config
docker run --rm -p 8080:8080 \
    -e VIDOCQ_CONFIG_DIR=/etc/myapp \
    -v $(pwd)/conf:/etc/myapp:ro \
    example/my-app:1.0.0

External override (ExternalFileConfigSource)

vidocq.properties placed in ${java.home}/conf/ (jlink image) or pointed to by $VIDOCQ_CONFIG_DIR is read with ordinal 250. See Reference for the full hierarchy.

Prerequisites and limitations

  • Strict JPMS — every dependency must be a named module. A jar without module-info.class nor Automatic-Module-Name breaks jlink.

  • Records serialised over REST — Champollion handles them via APT, not reflection. If an external dependency exposes records that are not generated, declare a JSON-B Converter<T>.

  • Custom java.util.logging Handler — declare the module in logging.properties so jlink embeds it (handlers=com.example.MyHandler).

  • macOS app-image — the bundle requires a valid --app-version; the plugin defaults to the project Maven version.

See vidocq/JLINK.md §6 and §8 for the full list of known limitations.

Next steps

  • Usage — packaging workflows

  • Reference — configuration keys

  • vidocq/JLINK.md — internal packaging documentation