Quarkus Quickstart
This guide serves as a quickstart on how to create a Quarkus app, briefly presenting the key functionalities that Quarkus provides, both for beginners and experienced developers.
Introduction to Quarkus
To get a first introduction to Quarkus, you can read the Quarkus introduction guide. To get a brief overview of where you can find the important Quarkus related guides, follow the chapter guide to the reader. Also, see the comparison of the advantages and disadvantages of a Quarkus application compared to the alternative framework Spring. This comparison will be supported by our performance comparison between Spring and Quarkus, which demonstrates the lower resource consumption and startup time of Quarkus applications.
Installation of Tools and Dependencies
First, we need to install some dependencies and tools before we can start programming. Our tool devonfw-ide comes with many development tools for you. We need to install the following tools for this guide:
-
Maven
-
Java
-
any IDE (devonfw-ide supports Eclipse, Intellij and VScode)
-
Docker
We recommend installing the devonfw-ide with the tools, but if you already have your system configured and the tools above installed, you can skip to Bootstrap a Quarkus Project, otherwise we will show you how to set up and update your devonfw-ide.
-
Install devonfw-ide
Follow the Setup to install the devonfw-ide with Java, Maven, Eclipse and VScode.-
Command to install Docker
devon docker setup
-
-
Update devonfw-ide
As we are still working on improving devonfw-ide, we recommend to update your already installed devonfw-ide and tools in order to include essential features for cloud development with Quarkus that you could be missing.
Use the commands devon ide update, devon ide update software, and devon ide scripts to update devonfw-ide and all installed software.
Go to the main folder under workspaces of the devonfw-ide installation. We will create the project there.
Bootstrap a Quarkus Project
Quarkus provides multiple ways to bootstrap a project. The option to bootstrap a project via the command-line is shown in the Quarkus getting started guide Bootstrap the project. Quarkus also provides a project builder where you can select some extensions, the build tool for your project, and if you want, some starter code. This will deliver a project skeleton with the configured project dependencies and also contributes the information to compile the application natively. To get some recommendations on starter templates, follow the guide on: template recommendations.
|
Note
|
By creating a Quarkus project from the command-line or with the project builder, you get a different project structure and have to adapt it to the devon4j conventions shown in the next Chapter. |
Project Structure
We provide a recommendation and guideline for a modern project structure to help organize your project into logically related modules. In order to comply with the requirements of modern cloud development and microservice architectures, follow the guide and apply the modern project structure to your project. You can also find similar modules in our example projects.
Introduction to Quarkus Functionality
Before we start programming, you should first have a look at the functionality of Quarkus.
-
Getting started guide from Quarkus
This guide presents a good overview of the functionality of Quarkus. The simple Greeting Service gives a brief introduction into concepts like CDI, testing, dev mode, packaging, and running the app. -
From Spring to Quarkus
For experienced Spring developers that have already followed devon4j guidelines, you can read our guide to getting started with Quarkus for Spring developer, as it goes more into the differences that can give you a more detailed comparison to Spring.-
Migrate a Spring app to Quarkus
This guide shows how to migrate a Spring application to a Quarkus application with devon4j conventions.
-
Create a REST service
Now let’s create our first REST CRUD service with Quarkus. We give you the options of using a guide to start to code the service yourself or to just download a service that’s ready to use.
-
Create the service yourself
There is a good Quarkus guide for a simple JSON REST service that will guide you through your first application and help you with implement the definition of endpoints with JAX-RS and an Entity that will be managed by the service, and also how to configure the JSON support. -
Use an existing Quarkus project
You don’t want to code a service and just want to test some Quarkus functionalities? Just load a Quarkus sample project provided for every existing quickstart guide and the supported framework. Our Team also provides some Quarkus applications that are working and can be loaded and tested.-
reference project is a service that manages products. It contains the devon4j modern project structure, pagination, queries, a Postgres database, SwaggerUI, and support for Kubernetes deploy. To add OpenTelemetry support, see the following guide. This project will be steadily improved and is used to showcase the abilities of Quarkus with devon4j.
-
minimal Quarkus project is just the Quarkus project from a getting started with Quarkus guide with a Greeting Services modified with the correct modern structure mentioned in the chapter Project Structure
-
OpenAPI generation
We provide a guide with a short introduction to the OpenAPI specification with two plugins that are important in a Quarkus Context.
A more detailed usage guide to the Smallrye Plugin is provided by Quarkus OpenAPI and Swagger guide.
How to Integrate a Database
The next step for our REST service would be to integrate a database to store the objects of the entity.
With Quarkus, adding a database can be easy, because Quarkus can take over the build-up and connection process. First, you should understand our guides on the concepts of working with data. Then, we will show how to integrate a database with Quarkus.
-
General devon4j JPA guide
To get an insight into the general JPA usage, read the JPA guide containing a general explanation of the Java Persistence API. -
Difference to SpringData
If you have already worked with SpringData, this is also partially supported with Quarkus. This is explained in more detail in this SpringData Guide.
-
Quarkus zero config dev mode
Starting with the database implementation in Quarkus, we recommend for beginners to use the DEV mode Zero Config Setup (Dev Services). This is especially great for testing the code without a database set up. Quarkus does all the work for you and configures a database and creates the database and tables (schemas) for you.-
Configuration Properties
A list of all database configuration properties for the Dev services
-
-
Integrate a simple Hibernate ORM database
The zero config setup only works with the Dev mode, it’s comfortable in the first phases of the creation of your service but if the goal is to also get a deployable version, you have to create your own database and integrate it. This Quarkus guide shows, how to integrate a Hibernate ORM database with an example service.-
Configuration list for JDBC
A list of all configuration that is possible with a JDBC configuration properties
-
-
Reactive CRUD application with Panache
Quarkus unifies reactive and imperative programming. Reactive is an architectural principle to build robust, efficient, and concurrent applications. For an introduction into reactive and how Quarkus enables it, follow this Quarkus reactive architecture article and also the reactive quickstart. To get started with reactive and implement reactive methods, you can follow the Quarkus reactive guide. The reactive guide uses the Quarkus based implementation of a Hibernate ORM called Panache. The implementation is not our first choice with devon4j and therefore not part of our recommendations, but to understand the reactive guide you can read the Hibernate ORM with Panache guide first to prevent possible problems following the guide.
|
Note
|
You need an installed Docker version for the zero config setup. |
For schema-based databases, we recommend migrating databases with Flyway. In that case, our general migration guide can give you an overview if you are not familiar with migration. .. Flyway guide for Quarkus This Quarkus guide will show how to work with the Flyway extension in a Quarkus application. This should be used if you start your own database and do not leave the creation to quarkus.
Testing a Quarkus Application
After we have built the service, we have to verify it with some tests. We will give you some guidelines to implement some test cases.
-
General testing guide
For users that aren’t familiar with the devon4j testing principles, we created a general best practices and recommendations guide for testing.-
Our guide for testing with Quarkus In addition, we also provide a guide that specifically addresses the testing of a Quarkus application.
-
Most of the Quarkus applications are already equipped with a basic test and our reference project provides some further test cases. If you want to improve and extend the tests, you can also follow the large Quarkus guide for testing.
Packaging of a Quarkus application and creation of a native executable
Quarkus applications can be packaged into different file types. The following link will show you how to build them and give you a short explanation of the characteristics of these files.
To package an application, use the command mvn package and Quarkus will generate the output in the /target folder. For the native executables, the command needs more parameters, which is explained in the link above.
Configure the Output with these configuration properties
Create and build a Docker Image
Quarkus supports Jib, S2I and Docker for building images. We focus on building a Quarkus App with Docker. You get a generated Dockerfile from Quarkus in the src/main/docker folder of any project generated from Quarkus. There are multiple Dockerfiles.
-
Dockerfile.jvm
Dockerfile for Quarkus application in the JVM mode. running in Red Hat Universal Base Image 8 Minimal Container -
Dockerfile.legacy-jar
DockerFile for Quarkus application in JVM mode with the legacy jar running in Red Hat Universal Base Image 8 Minimal Container. -
Dockerfile.native
Dockerfile using the native executable running in Red Hat Universal Base Image 8 Minimal container. -
Dockerfile.native-distroless The native file will run in a Distroless container. Distroless images are very small containers with just the application and runtime dependencies and without the other programs that come with a Linux distribution.
For more information to the different executables go back to the chapter Packaging of a Quarkus application and creation of a native executable
To simply build and run a Docker image, you can follow the instructions Quarkus provides for every Dockerfile in the comments block.
Docker commands example for the JVM Dockerfile from our reference project
#### # This Dockerfile is used in order to build a container that runs the Quarkus application in JVM mode # # Before building the container image run: # # ./mvnw package # # Then, build the image with: # # docker build -f src/main/docker/Dockerfile.jvm -t quarkus/quarkus-basics-jvm . # # Then run the container using: # # docker run -i --rm -p 8080:8080 quarkus/quarkus-basics-jvm # # If you want to include the debug port into your docker image # you will have to expose the debug port (default 5005) like this : EXPOSE 8080 5050 # # Then run the container using : # # docker run -i --rm -p 8080:8080 -p 5005:5005 -e JAVA_ENABLE_DEBUG="true" quarkus/quarkus-basics-jvm # ###
Quarkus is also able to build the image while packaging the application, so you don’t have to execute the command from above.
To perform Docker builds with the generated Dockerfiles from above, you need to add the following extension to your project with the command mvn quarkus:add-extension -Dextensions="container-image-docker".
You also have to set the quarkus.container-image.build=true. You can add this to your application.properties or just append it to the packaging command like this: ./mvn package -Dquarkus.container-image.build=true.
If your needs exceed the instructions given by the file, we recommend to follow the Docker getting started guide to get familiar with Docker and customize the Dockerfiles according to your needs. To specify your container build, you can use the general container image configurations properties and the Docker image configurations properties when building and runnig Docker images.