Quickstart

Quickstart is the fastest way to run a Vertique application. By the end of this page you will have generated a REST application from the archetype, run its integration test suite, started it locally, and received a JSON response from its generated /hello endpoint.

Choose your path

This page covers the REST archetype. Two sibling archetypes generate a different starting application from the same build. Pick the row that matches what you are building before you continue:

Start	When to choose it
REST (this page)	An HTTP API, with no persistence and no event-bus services
Service contracts	Contract-based execution with generated injectable clients and managed service verticles
REST + PostgreSQL	An HTTP API backed by a real, Flyway-migrated PostgreSQL database

Prerequisites

• JDK 21
• Apache Maven

You need nothing else. Vertique 0.3.0 is published to Maven Central, so archetype:generate resolves the archetype and the starter it depends on without a local checkout or a local build.

Generate the application

Run this command from an empty directory of your choice. It creates a new rest-app project inside it.

VERTIQUE_VERSION is declared once below and reused for both the archetype version and the generated project’s vertiqueVersion property. 0.3.0 is the released version this documentation describes, resolved from Maven Central.

VERTIQUE_VERSION=0.3.0

mvn -B -ntp archetype:generate \
  -DarchetypeGroupId=dev.vertique \
  -DarchetypeArtifactId=vertique-archetype-rest \
  -DarchetypeVersion=$VERTIQUE_VERSION \
  -DgroupId=com.example \
  -DartifactId=rest-app \
  -Dversion=0.1.0-SNAPSHOT \
  -Dpackage=com.example.restapp \
  -DvertiqueVersion=$VERTIQUE_VERSION \
  -DinteractiveMode=false

Expected result: BUILD SUCCESS, and a new rest-app directory containing:

rest-app/AGENTS.md
rest-app/README.md
rest-app/config/application.json
rest-app/pom.xml
rest-app/src/main/java/com/example/restapp/AppComponent.java
rest-app/src/main/java/com/example/restapp/AppModule.java
rest-app/src/main/java/com/example/restapp/package-info.java
rest-app/src/main/java/com/example/restapp/resource/HelloResource.java
rest-app/src/main/java/com/example/restapp/resource/package-info.java
rest-app/src/test/java/com/example/restapp/ApplicationIT.java

Run the test suite

Working directory: rest-app/.

cd rest-app
mvn -ntp verify

This compiles the application, packages it, and runs its integration test class, ApplicationIT, against a real deployed instance on a random port. Expected result: BUILD SUCCESS, with the test summary reporting Tests run: 3, Failures: 0, Errors: 0, Skipped: 0. servesHello calls /hello and asserts the JSON message. servesLiveness calls the management /health/live endpoint and asserts an UP status. bootstrapReadsWorkingDirectoryConfig checks that startup configuration is read from the project’s config/ directory.

Start the application

Working directory: rest-app/.

mvn -ntp exec:java

This starts the application in the foreground and keeps running until you stop it, so leave this terminal open. The application starts on HTTP port 8080, which serves the REST API, and management port 9090, which serves health and management endpoints. See Configuration for how runtime configuration is loaded and changed.

Call the hello endpoint

In a separate terminal, with the application still running:

curl -s http://localhost:8080/hello

Expected result:

{"message":"Hello, Vertique!"}

Stop the application

Return to the terminal running mvn -ntp exec:java and press Ctrl+C.

Learn more

• Vertique REST application archetype: the archetype’s own reference, including the dependencies the generated project declares.
• vertique-starter-rest module reference: the starter the generated application depends on.
• What is Vertique?

Continue reading

• Previous: What is Vertique?
• Next: Agent skills