Quarkus Project

This project uses Quarkus, the Supersonic Subatomic Java Framework.

It showcases a diverse set of features and capabilities provided by the framework.

• HTTP REST API OpenAPI configured.
• Request input validation.
• Dependency injection.
• Database with PostgreSQL and Liquibase.
• OIDC/Oauth2/JWT handling with Keycloak.
• Docker, Kubernetes and OpenShift deployments.
• Unit testing (REST Assured, JUnit).
• Postman automated API testing.
• CI pipeline with GitHub Actions
• Works on native mode.

Running the application in dev mode

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

mvn quarkus:dev

Running the application with containers

Build and push of containers images are powered by Jib: https://quarkus.io/guides/container-image#jib.

See application.properties for container image options.

Instructions require docker installed.

Red Hat container registry login

docker login registry.redhat.io

Run from the CI upstream image build

./run.sh

Try the native or any other compatible image:

./run.sh ghcr.io/juliaaano/quarkus-native:latest

Build and run image locally:

./build.sh && ./run.sh localhost/juliaaano/quarkus

Build and test a native executable

test-native.sh

Playing with the app

In Quarkus DEV mode, there is no security enabled, the API can be accessed from:

• http://localhost:8080/q/swagger-ui

As a container, the app runs in PROD mode along a set of other services, which can be found in the docker-compose.yaml file.

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

OpenShift

Works with Kubernetes too, but then you need to take care of the database and ingress yourself.

oc new-project juliaaano
oc new-app --name=postgresql --template=postgresql-ephemeral -e POSTGRESQL_USER=quarkus -e POSTGRESQL_PASSWORD=password -e POSTGRESQL_DATABASE=quarkusdb --labels="app=quarkus-app"
kubectl create configmap liquibase --from-file=liquibase/ && kubectl label cm liquibase app=quarkus-app
kubectl apply -f manifests/
kubectl set env deployment quarkus APP_AUTHORIZATION_ENABLED=false
kubectl scale deployment quarkus --replicas 2
oc expose service quarkus --labels="app=quarkus-app"
curl -i "http://$(oc get route quarkus -o jsonpath='{.spec.host}')/q/health"

S2I: build image from source

These instructions are intended to be used in testing and development and not for CI/CD.

JVM build

oc new-build --binary=true --image=registry.redhat.io/ubi9/openjdk-17 --name=quarkus --labels="app=quarkus-app"
oc start-build quarkus --from-dir . --follow

Native build

mvn clean package -Pnative -Dquarkus.native.container-build=true
oc new-build --binary=true --docker-image=quay.io/quarkus/ubi-quarkus-native-binary-s2i:2.0 --name=quarkus-native --labels="app=quarkus-app"
oc start-build quarkus-native --from-file ./target/quarkus-app-1.0.1-runner --follow

Deployment

Once image is built and pushed to the registry, just set the image in the deployment:

oc set image deployment quarkus app=$(oc get istag quarkus:latest -o jsonpath='{.image.dockerImageReference}')

Review any steps above in OpenShift.

Clean up

kubectl delete all -l app=quarkus-app

Postman API testing

This project offers an automated setup of integration API testing with Postman.

Postman collections present in the postman folder can be imported and exported into the app and are automatically executed using docker compose with Newman under the hood.

The QUARKUS_APP_HOST var points to the system under test and can be adjusted accordingly.

mvn quarkus:dev
docker compose run --rm postman
QUARKUS_APP_HOST=http://localhost:8080 docker compose run --rm postman

Keycloak and JWT RBAC Security

When using docker compose, a Keycloak realm is automatically imported, so tokens can be issued and used with the application as follows:

export access_token=$(\
    curl -X POST http://localhost:50102/realms/quarkus/protocol/openid-connect/token \
    --user quarkus-api-test-client:"" \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=bob&password=password&grant_type=password&scope=api.pets:read' | jq --raw-output '.access_token' \
)
curl -v http://localhost:50101/api/pets -H "Authorization: Bearer "$access_token

export access_token=$(\
    curl -X POST http://localhost:50102/realms/quarkus/protocol/openid-connect/token \
    --user quarkus-api-test-client:"" \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=alice&password=password&grant_type=password&scope=api.pets:read api.pets:write api.pets:erase' | jq --raw-output '.access_token' \
)
curl -v -X POST http://localhost:50101/api/pets -H "Authorization: Bearer "$access_token -H "Content-Type: application/json" -d '{"species":"bird","breed":"krakatoo"}'

Misc

Test i18n localization:

curl -i -X PUT http://localhost:8080/api/pets/x -d '{}' -H 'Content-Type: application/json' -H 'Accept-Language: fr-FR'

Keycloak export:

docker exec -it quarkus-keycloak-1 /opt/keycloak/bin/kc.sh export --users realm_file --realm quarkus --file /tmp/export.json
docker exec -it quarkus-keycloak-1 cat /tmp/export.json | pbcopy