Vidocq Documentation

Cette page installe la CLI Vidocq, génère une application REST, la construit avec Maven standard et sert un premier endpoint — chaque commande ci-dessous est testée de bout en bout contre les artefacts 0.2.x publiés sur Maven Central. Si vous préférez ne pas utiliser la CLI, rendez-vous directement à l’annexe manuelle.

Prérequis

  • Java 25 (Temurin recommandé) — vérifiez avec java -version

  • Maven 3.9+ — vérifiez avec mvn -version

Avec SDKMAN! : sdk install java 25-tem && sdk install maven.

Étape 1 — Installer la CLI

curl -fsSL https://vidocq.dev/install.sh | sh

Sous Windows (PowerShell) :

irm https://vidocq.dev/install.ps1 | iex

Le script télécharge la dernière CLI publiée depuis Maven Central dans ~/.vidocq/cli et place un lanceur vidocq sur votre PATH. Vérification :

$ vidocq version
Vidocq CLI 0.2.1
Sans installeur ? Téléchargez vidocq-runtime-cli-<version>-cli.zip depuis Maven Central, dézippez-le où vous voulez et ajoutez son répertoire bin/ à votre PATH.

Étape 2 — Générer un projet

vidocq create --name todo --group-id com.acme --extension cassini-rest
cd todo

--extension cassini-rest (raccourci : -x) active Jakarta REST — qui apporte transitivement le serveur HTTP Chappe, CDI (Vauban) et JSON-B (Champollion). Le projet généré est un projet Maven JPMS standard :

todo/
  pom.xml                      (1)
  src/main/java/
    module-info.java           (2)
    com/acme/todo/TodoApp.java (3)
  src/main/resources/
    vidocq.properties          (4)
1 Hérite de io.vidocq.runtime:vidocq-runtime-parent:0.2.0 et câble le vidocq-runtime-maven-plugin pour que mvn package produise une distribution exécutable.
2 Descripteur de module, pré-rempli avec les requires/opens nécessaires à une app REST.
3 Le point d’entrée — démarre le runtime via VidocqBootstrap.
4 Configuration façon MicroProfile (vidocq.http.port=8080, …).
vidocq extension list --available liste toutes les extensions first-party, et vidocq help create détaille les options (--package, --parent-version, …).

Étape 3 — Écrire votre première ressource

Créez src/main/java/com/acme/todo/HelloResource.java :

package com.acme.todo;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/hello")
@ApplicationScoped
public class HelloResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello from Vidocq!";
    }
}

Aucun câblage supplémentaire : le processeur d’annotations Cassini génère l’adaptateur de dispatch à la compilation — zéro réflexion au runtime.

Étape 4 — Construire et lancer

mvn package
sh target/todo-0.2.0/bin/todo.sh

mvn package compile, exécute les générateurs de code et assemble une distribution autonome sous target/todo-0.2.0/ (lanceurs dans bin/, module path dans lib/). Dans un autre terminal :

$ curl http://localhost:8080/hello
Hello from Vidocq!

Le runtime démarre en bien moins d’une seconde — la ligne de log à repérer :

INFOS: Vidocq - Started in 90.940 ms (process running for 135 ms)

Étape 5 — Mode dev

mvn vidocq:dev

Le mode dev lance l’application sur son module path et surveille vos sources. Il s’appuie sur les propriétés vidocq.mainModule / vidocq.mainClass déjà présentes dans le pom généré.

vidocq dev et vidocq start (les commandes CLI, à distinguer du goal Maven) démarrent le runtime depuis le module path de la CLI elle-même et ne voient donc pas les extensions déclarées dans votre pom. Préférez mvn vidocq:dev et le lanceur packagé pour les apps à extensions.

Étape 6 — Ajouter des extensions au fil de l’eau

vidocq extension list --available
vidocq extension add knock-health
mvn package

extension add modifie votre pom.xml avec les bonnes coordonnées. Voir Usage pour les clés de configuration de chaque extension, et le tour des exemples pour une application REST + persistance complète (Mansart Data + H2).

Étape 7 — Packager pour la production

vidocq build jlink    # image runtime autonome (aucun java local requis)
vidocq build docker   # image de conteneur

Voir Usage pour les options jlink/jpackage/Docker et les notes AOT.

Annexe — Sans la CLI

La CLI est une commodité, pas une exigence. Le projet ci-dessus est du Maven standard — voici l’équivalent complet, copiable tel quel.

pom.xml :

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>io.vidocq.runtime</groupId>
        <artifactId>vidocq-runtime-parent</artifactId>
        <version>0.2.0</version>
        <relativePath/>
    </parent>

    <groupId>com.acme</groupId>
    <artifactId>todo</artifactId>
    <name>todo</name>

    <properties>
        <vidocq.mainModule>com.acme.todo</vidocq.mainModule>
        <vidocq.mainClass>com.acme.todo.TodoApp</vidocq.mainClass>
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.vidocq.runtime</groupId>
            <artifactId>vidocq-runtime-core</artifactId>
            <version>0.2.0</version>
        </dependency>
        <dependency>
            <groupId>io.vidocq.runtime.extensions.jakartaee.core</groupId>
            <artifactId>vidocq-runtime-cassini-rest-extension</artifactId>
            <version>0.2.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>io.vidocq.runtime</groupId>
                <artifactId>vidocq-runtime-maven-plugin</artifactId>
                <configuration>
                    <jvmArgs>-Dfile.encoding=UTF-8</jvmArgs>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>package</goal>
                        </goals>
                        <configuration>
                            <mainClass>${vidocq.mainModule}/${vidocq.mainClass}</mainClass>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <annotationProcessorPaths combine.children="append">
                        <path>
                            <groupId>io.vidocq.runtime.extensions.jakartaee.core</groupId>
                            <artifactId>vidocq-runtime-cassini-rest-extension-codegen</artifactId>
                            <version>0.2.0</version>
                            <type>pom</type>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
Les versions des dépendances sont volontairement épinglées : le dependencyManagement du parent publié utilise ${project.version}, donc une app qui s’y fierait doit hériter de la version du parent. Les deux blocs de configuration du vidocq-runtime-maven-plugin contournent des problèmes connus de la 0.2.0 (corrigés dans la prochaine release).

src/main/java/module-info.java :

module com.acme.todo {
    // APT-generated $$CassiniAdapter classes import @Generated (SOURCE retention).
    requires static java.compiler;

    requires jakarta.cdi;
    requires jakarta.inject;
    requires jakarta.ws.rs;
    requires jakarta.json.bind;

    requires io.vidocq.runtime.core;
    requires io.vidocq.runtime.extensions.jakartaee.core.cassini;
    requires io.vidocq.cassini.api;

    // JAX-RS and JSON-B reflect on resource classes and payload types.
    opens com.acme.todo;
}

Cet opens fonctionne parce que les resources vivent dans le même module que la classe principale. Dans une application multi-modules (p. ex. hexagonale, resources dans leur propre module Java), le système de modules ne permet à un module d’ouvrir que ses propres packages : l'`opens` doit migrer dans le module qui contient les classes, et le module runtime le scanne via <scanDependencies>. Voir Usage — Applications multi-modules.

src/main/java/com/acme/todo/TodoApp.java :

package com.acme.todo;

import io.vidocq.runtime.core.VidocqBootstrap;

public final class TodoApp {

    public static void main(String[] args) {
        VidocqBootstrap.create()
                .configure()
                .start()
                .awaitShutdown();
    }
}

src/main/resources/vidocq.properties :

# Vidocq application configuration
vidocq.http.port=8080

Ajoutez ensuite la HelloResource de l’étape 3 et reprenez à l’étape 4 (mvn package) — le déroulé est identique.

Étapes suivantes