Quarkus (Native Image + Docker Deploy OpenShift)

Learn about QuarkusIO and if it's an alternative for bringing Java more effectively to the cloud. Live hot reloaded changes example, creating native docker and deploy the image to openshift example.

1. Introduction

In this article, you will learn a new hot technology Quarkus IO how it became alternatively to bring the java applications to the cloud.

You will learn

• Creating Quarkus Application with Quarkus init.
• Auto Hot Reload Chances feature
• Build and Start the container
• Building Docker container
• Deploying docker image to Openshift.

This gives more clear to use where the instances are created and destroyed frequently. And also boot time and serving the first request gives a much better user experience.

Always, Python and javascript are coming in the first place to deploy the apps into the cloud. But, let us see how to use Quarkus to deploy the apps into the cloud.

Spring Boot Cloud Related Books

Guide to QuarkusIO

2. QuarkusIO

Quarkus always gives the less boot time and servers the first request very fast as compare to Spring Boot 2.0 applications.

It is integrated with GraalVM that makes Quarkus will come ahead of time (AOT).

This is built to support all frameworks along with support for all extensions such as JAX-RS, CDI,  Web, ORM, and Messages including Hibernate, JMS, Kafka, OpenShift, Kubernetes and vert.x for auto-reload changes.

3. Quarkus First Hello World Application

You can create a maven application with the below command.

[mvn io.quarkus:quarkus-maven-plugin:0.13.1:create \
    -DprojectGroupId=com. javaprogramto.quarkus \
    -DprojectArtifactId=quarkus-project \
    -DclassName="com.javaprogramto.quarkus.HelloResource" \
    -Dpath="/hello"]

Or You can create from https://code.quarkus.io/

Provide all the information such as artifact id and add the dependencies.. here we have added Kubernetes also to see the default files.

4. Quarkus Project Structure

The following is the default project structure with JAX-RS and Kubernates.

It has created dockerfile for JVM and native.

MacBook-Pro-2:code-with-quarkus$ tree

.

├── README.md

├── code-with-quarkus.iml

├── mvnw

├── mvnw.cmd

├── pom.xml

└── src

    ├── main

    │   ├── docker

    │   │   ├── Dockerfile.jvm

    │   │   └── Dockerfile.native

    │   ├── java

    │   │   └── org

    │   │       └── javaprogramto

    │   │           └── quarkus

    │   │               └── ExampleResource.java

    │   └── resources

    │       ├── META-INF

    │       │   └── resources

    │       │       └── index.html

    │       └── application.properties

    └── test

        └── java

            └── org

                └── javaprogramto

                    └── quarkus

                        ├── ExampleResourceTest.java

                        └── NativeExampleResourceIT.java

15 directories, 12 files

5. Default Rest API Example in Quarkus

This is the one created with the example demo and "hello" endpoint will return response as "hello world".

package org.javaprogramto.quarkus;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/hello")
public class ExampleResource {

    @GET    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "hello world";
    }
}

Below Two files you can ignore for now and just showing the contents. If you are interested and have some idea about docker, Please go through it.

Otherwise, Directly jump into section 6l

Dockerfile.native:

####
# This Dockerfile is used in order to build a container that runs the Quarkus application in native (no JVM) mode
#
# Before building the docker image run:
#
# mvn package -Pnative -Dquarkus.native.container-build=true
#
# Then, build the image with:
#
# docker build -f src/main/docker/Dockerfile.native -t quarkus/code-with-quarkus .
#
# Then run the container using:
#
# docker run -i --rm -p 8080:8080 quarkus/code-with-quarkus
#
###
FROM registry.access.redhat.com/ubi8/ubi-minimal:8.1
WORKDIR /work/
COPY target/*-runner /work/application

# set up permissions for user `1001`
RUN chmod 775 /work /work/application \
  && chown -R 1001 /work \
  && chmod -R "g+rwX" /work \
  && chown -R 1001:root /work

EXPOSE 8080
USER 1001

CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]

Dockerfile.jvm

####
# This Dockerfile is used in order to build a container that runs the Quarkus application in JVM mode
#
# Before building the docker image run:
#
# mvn package
#
# Then, build the image with:
#
# docker build -f src/main/docker/Dockerfile.jvm -t quarkus/code-with-quarkus-jvm .
#
# Then run the container using:
#
# docker run -i --rm -p 8080:8080 quarkus/code-with-quarkus-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/code-with-quarkus-jvm
#
###
FROM registry.access.redhat.com/ubi8/ubi-minimal:8.1

ARG JAVA_PACKAGE=java-11-openjdk-headless
ARG RUN_JAVA_VERSION=1.3.5

ENV LANG='en_US.UTF-8' LANGUAGE='en_US:en'

# Install java and the run-java script
# Also set up permissions for user `1001`
RUN microdnf install curl ca-certificates ${JAVA_PACKAGE} \
    && microdnf update \
    && microdnf clean all \
    && mkdir /deployments \
    && chown 1001 /deployments \
    && chmod "g+rwX" /deployments \
    && chown 1001:root /deployments \
    && curl https://repo1.maven.org/maven2/io/fabric8/run-java-sh/${RUN_JAVA_VERSION}/run-java-sh-${RUN_JAVA_VERSION}-sh.sh -o /deployments/run-java.sh \
    && chown 1001 /deployments/run-java.sh \
    && chmod 540 /deployments/run-java.sh \
    && echo "securerandom.source=file:/dev/urandom" >> /etc/alternatives/jre/lib/security/java.security

# Configure the JAVA_OPTIONS, you can add -XshowSettings:vm to also display the heap size.
ENV JAVA_OPTIONS="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager"

COPY target/lib/* /deployments/lib/
COPY target/*-runner.jar /deployments/app.jar

EXPOSE 8080
USER 1001

ENTRYPOINT [ "/deployments/run-java.sh" ]

6. Run and Test Changes

As of now, You feel all are good in place for the Resteasy JAX-RS endpoints and now time to start the application to hit the first request.

And also here there is no main application with main() method similar to the Spring Boot application.

First, open the terminal and run the below command and go the where the pom.xml file is located.

./mvnw compile quarkus:dev:

This command will download all the dependencies first and next then compiles and start the container.

MacBook-Pro-2:code-with-quarkus$ ./mvnw compile quarkus:dev

[INFO] Scanning for projects...

[INFO] 

[INFO] ------------< org.javaprogramto.quarkus:code-with-quarkus >-------------

[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT[INFO] --------------------------------[ jar ]---------------------------------

[INFO] 

[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ code-with-quarkus ---

[INFO] Using 'UTF-8' encoding to copy filtered resources.

[INFO] Copying 2 resources

[INFO] 

[INFO] --- maven-compiler-plugin:3.8.1:compile (default-compile) @ code-with-quarkus ---

[INFO] Changes detected - recompiling the module!

[INFO] Compiling 1 source file to /Users/Documents/Quarkus/code-with-quarkus/target/classes[INFO]

 [INFO] --- quarkus-maven-plugin:1.4.1.Final:dev (default-cli) @ code-with-quarkus ---Listening for transport dt_socket at address: 5005

Downloaded from central: 

https://repo.maven.apache.org/maven2/io/quarkus/quarkus-kubernetes-deployment/1.4.1.Final/quarkus-kubernetes-deployment-1.4.1.Final.jar (89 kB at 9.2 kB/s)Downloaded from central: 

https://repo.maven.apache.org/maven2/io/dekorate/kubernetes-annotations/0.11.5/kubernetes-annotations-0.11.5-noapt.jar (321 kB at 33 kB/s)Downloaded from central: 

https://repo.maven.apache.org/maven2/io/fabric8/kubernetes-model/4.9.0/kubernetes-model-4.9.0.jar (12 MB at 1.0 MB/s)Downloaded from central: 

https://repo.maven.apache.org/maven2/io/dekorate/dekorate-dependencies/0.11.5/dekorate-dependencies-0.11.5.jar (19 MB at 1.1 

MB/s)__  ____  __  _____   ___  __ ____  ______  --/ __ \/ / / / _ | / _ \/ //_/ / / / __/  -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \   --\___\_\____/_/ |_/_/|_/_/|_|\____/___/   2020-05-03 20:15:10,225 

INFO  [io.quarkus] (Quarkus Main Thread) code-with-quarkus 1.0.0-

SNAPSHOT (powered by Quarkus 1.4.1.Final) started in 1.729s. Listening on: http://0.0.0.0:80802020-05-03 20:15:10,228 

INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.2020-05-03 20:15:10,228 

INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, kubernetes, resteasy]

Now the services is started on port 8080. You can see from console what are the installed libraries on this [cdi, Kubernetes, resteasy]

Let us test the service with the curl command.

MacBook-Pro-2:code-with-quarkus$ curl localhost:8080/hello

hello world

This has produced the output hello world.

7. Quarkus Hot Reload Feature

Now, the power of Quarkus is to fetch the latest changes when a request come to the server. Hot-reload capability is added by default with the command of "./mvnw compile quarkus:dev:"

In simpler words, All the changes to java and configuration files are compiled when next request comes or the browser is refreshed.

Now, appended the extra text to the response and then just hit the request again.

@Path("/hello")
public class ExampleResource {

    @GET    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "hello world, Welcome reader.";
    }
}

After hitting curl command again you will see the below changes in the console and get latest response.

[2020-05-03 20:25:04,012 INFO  [io.qua.dep.dev] (vert.x-worker-thread-1) Hot replace total time: 0.777s ]

Internally, the vert-x thread will be pulling the latest changes from compiled versions.

[MacBook-Pro-2:code-with-quarkus$ curl localhost:8080/hellohello, world, Welcome reader.]

Similarly, you can bundle the application as jar and run the application with java -jar command..

To create the jar file:

[./mvnw package]

To start the application:

After packaging success, you will see the two jars in the target folder.

[code-with-quarkus-1.0.0-SNAPSHOT.jar
code-with-quarkus-1.0.0-SNAPSHOT-runner.jar]

You should use code-with-quarkus-1.0.0-SNAPSHOT-runner.jar file in java command to start the container.

[java -jar /target/code-with-quarkus-1.0.0-SNAPSHOT-runner.jar]

8. Quarkus Native Image

Usually, native images will help in improving the boot startup time and serve response first.

To create a native image file, you must have GraalVM installed on your machine and must have set GRAALVM_HOME, JAVA_HOME. Otherwise, you will get the below error.

Command to create all the code for the native image

[./mvnw package -Pnative]

Error:

[ Failed to execute goal io.quarkus:quarkus-maven-plugin:1.4.1.Final:build (default) on project code-with-quarkus: Failed to build quarkus application: io.quarkus.builder.BuildException: Build failure: Build failed due to errors[ERROR] [error]: Build step io.quarkus.deployment.pkg.steps.NativeImageBuildStep#build threw an exception: java.lang.RuntimeException: Cannot find the `native-image` in the GRAALVM_HOME, JAVA_HOME and System PATH. Install it using `gu install native-image`]

If execution is a success then it will take a few seconds to generate artifacts properly.

To verify artifacts

[./mvnw package verify -Pnative]

To create a docker image, you must have a running docker in the machine.

This command generates Linux 64 bit executables.

[./mvnw package -Pnative -Dnative-image.docker-build=true]

Docker Image Creation:

[docker build -f src/main/docker/Dockerfile.native -t Quarkus/code-with-quarkus .]

To run the docker image

[docker run -i --rm -p 8080:8080 Quarkus/code-with-quarkus]

9. Deploying to OpenShift

Once you're done with the testing locally using Docker then you are ready to deploy our container to OpenShift. 

Assuming that you have the Docker image on our registry and you can deploy the application following the steps below:

oc new-build --binary --name=code-with-quarkus -l app=code-with-quarkus
oc patch bc/quarkus-project -p '{"spec":{"strategy":{"dockerStrategy":{"dockerfilePath":"src/main/docker/Dockerfile.native"}}}}'
oc start-build quarkus-project --from-dir=. --follow
oc new-app --image-stream=quarkus-project:latest
oc expose service quarkus-project

Command to start the application:

[oc get route]

Finally, You'll have to access the same endpoint 

[$ curl http://quarkus-project-myproject.192.168.64.2.nip.io/hello]

Response:

[hello world, Welcome reader]

10. Conclusion

[oc new-build --binary --name=code-with-quarkus -l app=code-with-quarkus

oc patch bc/quarkus-project -p '{"spec":{"strategy":{"dockerStrategy":{"dockerfilePath":"src/main/docker/Dockerfile.native"}}}}'


oc start-build quarkus-project --from-dir=. --follow


oc new-app --image-stream=quarkus-project:latest


oc expose service quarkus-project]

In conclusion, You've seen how to start working with Quarkus Hello World application and how to create the docker image and start the container.

And also steps to deploy the quarkus app into OpenShift

All the code is shown in this article is over GitHub.

You can download the project directly and can run in your local without any errors.

View on GitHub 

Download 

If you have any queries please post in the comment section.