test-quarkus/README.md

test-quarkus

This project uses Quarkus, the Supersonic Subatomic Java Framework.

If you want to learn more about Quarkus, please visit its website: https://quarkus.io/ .

Building and deploying natively

Build the native image with the Mandrel-based multi-stage Dockerfile and push it to a remote Docker host over an SSH tunnel. The script starts a temporary registry:2 container on the remote (localhost only), forwards it to the build machine, pushes the image through that tunnel, then pulls and retags it on the remote Docker daemon. No external registry is required.

./scripts/build-and-push.sh --remote deploy@prod.example.com

The script reads artifactId and version from pom.xml for the image name and version tag, builds for linux/amd64, and verifies the image is present on the remote after pushing. On the remote (and locally) that push is tagged three ways, all pointing at the same image:

• <name>:<version> — the version from pom.xml or --tag
• <name>:latest — moved to this push on every successful deploy
• <name>:sha256-<12 hex chars> — immutable tag taken from the registry digest

The temporary registry container and SSH tunnel are removed when the script finishes. See ./scripts/build-and-push.sh --help for all flags.

To remove leftover temporary registry containers and localhost:<port>/... image tags on the remote (for example after an interrupted push or manual tests):

./scripts/build-and-push.sh --remote deploy@prod.example.com --cleanup

This does not rebuild or push; it only needs SSH access to the remote host.

It can be invoked from any directory: by default it resolves the project root from the script's own location. Override with --project-dir PATH or the PROJECT_DIR environment variable when needed.

SSH config aliases

--remote accepts either an explicit user@host[:port] or a bare alias that is resolved from ~/.ssh/config. The matching Host block supplies HostName, User, Port and IdentityFile automatically:

# ~/.ssh/config
Host prod
    HostName prod.example.com
    User deploy
    Port 22
    IdentityFile ~/.ssh/deploy_ed25519

./scripts/build-and-push.sh --remote prod
# Resolves to deploy@prod.example.com:22 using ~/.ssh/deploy_ed25519

--ssh-key always overrides the config IdentityFile. Use --ssh-config PATH to point at a non-default config file.

Running the application in dev mode

You can run your application in dev mode that enables live coding using:

./mvnw compile quarkus:dev

NOTE: Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/.

Packaging and running the application

The application can be packaged using:

./mvnw package

It produces the quarkus-run.jar file in the target/quarkus-app/ directory. Be aware that it’s not an über-jar as the dependencies are copied into the target/quarkus-app/lib/ directory.

The application is now runnable using java -jar target/quarkus-app/quarkus-run.jar.

If you want to build an über-jar, execute the following command:

./mvnw package -Dquarkus.package.type=uber-jar

The application, packaged as an über-jar, is now runnable using java -jar target/*-runner.jar.

Creating a native executable

You can create a native executable using:

./mvnw package -Dnative

Or, if you don't have GraalVM installed, you can run the native executable build in a container using:

./mvnw package -Dnative -Dquarkus.native.container-build=true

You can then execute your native executable with: ./target/test-quarkus-1.0.0-SNAPSHOT-runner

If you want to learn more about building native executables, please consult https://quarkus.io/guides/maven-tooling.

Related Guides

• REST Jackson (guide): Jackson serialization support for Quarkus REST. This extension is not compatible with the quarkus-resteasy extension, or any of the extensions that depend on it
• SmallRye Health (guide): Monitor service health

Provided Code

REST

Easily start your REST Web Services

Related guide section...

SmallRye Health

Monitor your application's health using SmallRye Health

Related guide section...