Build and deploy a Quarkus application to OpenShift in minutes

Introduction

Looking for a quicker way to get your development projects up and running? This exercise demonstrates how you can go from initial app idea to prototype code in as little as five minutes using Quarkus, Podman Desktop, and the no-cost Developer Sandbox for Red Hat OpenShift.

We'll scaffold a Quarkus application, build a container image locally using Podman Desktop, then see how to install, run, and test the application in the Developer Sandbox from the command line.

Prerequisites

In order to follow along with this activity, you'll need the following: 

• A Developer Sandbox for Red Hat OpenShift account. See How to access the Developer Sandbox for Red Hat OpenShift for a step-by-step guide.
• The oc command-line interface (CLI), which lets us interact with the Developer Sandbox from our terminal. Once you have set up your Developer Sandbox account and logged in, you can download the CLI directly from the Developer Sandbox by clicking the question mark icon.
• Podman and Podman Desktop installed locally.
• The latest version of the Red Hat build of Quarkus (so you can use the brilliant quarkus dev features).

Bootstrap the Quarkus application

The first step is to get some nice Quarkus source code from the Quarkus code scaffolding page. For this example, I will fall back on my old favorite, RESTEasy Classic.

Set your Group appropriately (I always use org.uth), give your app a name, and choose the RESTEasy Classic option.  Make sure the Starter Code is set to Yes, then click the Generate your application button (Figure 1).

Download the juicy ZIP file full of Quarkus goodness and unzip it in an empty directory. This scaffolded code gives you all the bits and pieces for your Quarkus application, including a Containerfile we will use shortly.

Edit the Java code

For the sake of this quick example, let's add another endpoint to the RESTful application at a subdirectory to differentiate the code. If you go into the root directory where you extracted the ZIP file, you will see a directory called src. This directory contains all the source code for the app, including the one-stop configuration file (application.properties) and the Docker/Podman build files for creating a composite Quarkus application (which we will use in a later step).

For now, edit the Java file at the bottom of the src/main/java/ directory structure (there will be subdirectories based on your organization name, but the file will be called GreetingResource.java). This Java file is the scaffolded example from the Quarkus code page. Add the additional method and annotations for the @Path("/subdir"):

package org.uth;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
@Path("/hello")
public class GreetingResource {
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello RESTEasy";
    }

    @Path("/subdir")
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String systemTime() {
        return "Systime: " + System.currentTimeMillis();
    }
}

Test with Quarkus dev mode

One of the nicest features of Quarkus is the dev mode feature, which enables hot deployment with background compilation. We will use it now to see if our code change has worked. At the root directory point where the pom.xml lives, type quarkus dev to run up the application from the source code. To test it, go to another terminal window and type:

curl http://localhost:8080/hello/subdir

If all has gone well, you should see a microsecond system time. As a quick test to show the power of the Quarkus dev mode, in the new terminal window, edit the file to change Systime to something else, and save. Repeat the cURL command, and whatever change you made will be reflected in the output.

Prepare the image build components

So, Quarkus dev mode works a treat, but the Containerfiles provided to build an image from the source need some binary components that aren't created as part of the dev mode.

Exit the dev mode in the terminal where it is running (just hit q to quit).

To quickly create the necessary components, type the following command at the root directory (where the pom.xml lives):

./mvnw clean install

If you look in the directory, there is a new folder called target where the binary artifacts are staged/created. If you do a directory listing, you will see a subdirectory called quarkus-app. The Containerfile uses this as the application component when building the composite image.

Build the image

For this step, you could use Podman at the command line, but we're going to use Podman Desktop to show how easy it is.

Fire up the Podman Desktop application, go to the Images tab, and select Build Image. This will give you a simple wizard to enter the information needed to do the image build.

We will use the scaffolded Containerfile and the generated binary artifacts. Click Select Containerfile to build and follow the directory structure from your root directory (where the pom.xml is and where you unzipped the source) down through src/main/docker. Click the Dockerfile.jvm file.

Note: Dockerfile and Containerfile are interchangeable terms; both refer to a file that lists the steps to take to build an image.

There's a little gotcha here: Because the Containerfile was in a subdirectory, we have to give the Podman application a different context directory to look for the components. The Containerfile makes a direct reference to a target subdirectory, and because the Containerfile was down in the src/xxx directory, it will set the context directory there by default. Change the Build Context Directory to your root directory (i.e., remove the /src/main/docker bit).

Change the name to something simple and memorable, and add a tag that isn't :latest. (It's bad practice to use the :latest tag, as any builds you do overwrite any previous image with the :latest tag.) See Figure 2.

Now hit Build. If all goes well, it will complete pretty quickly. If you then navigate to the Images tab, you should see a generated image as illustrated in Figure 3.

Test the image

From the Images tab in Podman Desktop, locate the image you just created, and click the Run icon on the far right to start a container using that image. In the wizard, leave everything as default (as we just want to test our endpoint quickly). Click Start Container.

Podman Desktop should switch to the Containers tab, and you will see a container running (with an improbable name). Pop back to a terminal window and enter:

curl http://localhost:8080/hello/subdir

You should see the system time and the code change you made earlier reported as a response. The image works!

Set up the Developer Sandbox interaction

Now comes the fun stuff. To start, we need to log into the Developer Sandbox. When you log in, you will be presented with the Developer viewpoint and offered a tour. If you have time, take the tour—it's very much worth it.

When you're ready to proceed, click the drop-down menu in the upper-right corner of the window (where your username is displayed) and select Copy Login Command. This opens a new window where you are given the command to log onto the Developer Sandbox via the oc cli. Click Display Token, then copy the oc login command to paste and execute in your terminal window. 

This command uses the oc tool (installed as part of the prerequisites) to log you onto the Developer Sandbox from your terminal. You can now interact with your project (which will be [username]-dev) directly, which is how we'll install and run the application we just created an image for.

Connect Podman to the Developer Sandbox

To install and run the application, we are going to log Podman onto the Sandbox itself. This lets us use the Developer Sandbox integrated registry, which is how OpenShift controls and manages all images on the system directly.

A small caveat: The Developer Sandbox is actually a number of OpenShift clusters, and when you set up your account, you get assigned to one of them. In order to log Podman onto the appropriate cluster, you need to determine which cluster you're assigned to.

At the terminal, type:

oc whoami --show-server=true

This command (which we will also use to get the token to log on to the registry) gives us information about who we are and where we are logged onto. The output of that command will look a little like this:

https://api.sandbox-m3.1530.p1.openshiftapps.com:6443

This is the RESTful API endpoint for our cluster (yours might look slightly different).

We are now going to use a neat little part of the oc whoami command to log us directly into the registry. This is the command we are going to use, but we need to change the target registry depending on the output of your oc whoami --show-server=true:

podman login -u testuser -p $(oc whoami -t) default-route-openshift-image-registry.apps.sandbox-m3.1530.p1.openshiftapps.com

Important: Replace the registry route with the output of your oc whoami --show-server=true without the https and port number.

If it all works, Podman will return a Login Succeeded! message. At this point, we can push images directly from our local system into the Developer Sandbox registry.

Upload the image to the Developer Sandbox

Now we'll take the Quarkus image that we built and upload it directly into the Developer Sandbox registry so we can play with it in our sandbox project space.

To do this, we need to know two things: the ID of the image on our local Podman storage and the project name on the Developer Sandbox. To get the ID, type:

Podman images

Copy the image ID displayed next to the image you created—this ID tells Podman which image to upload.

Your Sandbox project name is defined for you when you set up the Sandbox and will take the form of [your user_id]-dev (for example, myuser-dev). You can get this by typing:

oc project

We also need the Registry endpoint; this is the last part of the Podman login command you used above (the default-route-openshift-image-registry.apps.etc.etc.).

Now we will upload the image using a command similar to this:

Podman push 3f2da1cf1d80 default-route-openshift-image-registry.apps.sandbox-m3.1530.p1.openshiftapps.com/myuser-dev/quickquarkus:latest

Note the bold components. You will need to change the image ID, the target registry address, your project name, and a name for the application, like so:

Podman push YOUR_IMAGE_ID default-route-openshift-image-registry.YOUR_SANDBOX_CLUSTER/YOUR_PROJECT/PICK_A_NAME:latest

Run the Quarkus application

At this point, we have created the code, built and tested it, created the image, and uploaded the image ready to be used in the sandbox. All that is left now is to run it and have a play.

There are many ways to get your Quarkus application into the Developer Sandbox for Red Hat OpenShift. What we have done here is the basic step-by-step approach from scratch using some of the best tools from Red Hat Developer, but you could do the following instead:

• Build a fat-jar: Add quarkus.package.type=uber-jar into the application.properties file and simply do a /mvnw clean package. You can upload this JAR file directly into the Developer Sandbox from the Developer Add+ menu.
• Use Maven to upload directly: Add the quarkus-OpenShift dependency in the pom.xml and simply do a /mvnw clean package -Dquarkus.kubernetes.deploy=true.
• Use Quarkus itself: Simply type quarkus deploy in the root directory (once you log in to the Developer Sandbox, it will deploy into your project).

All of these make some assumptions as to what you want the format of the application to be (i.e., a Kubernetes deployment). The approach we will describe here allows you to configure any aspect of the deployment, which is much more flexible.

Go to the Developer Sandbox in the browser and navigate to the Developer viewpoint (top left of the interface). Click +Add → Container Images. We are going to deploy an application directly from images that we have access to (the one we just uploaded).

In the Deploy Image tab, select Image Stream Tag from Internal Registry. Because we uploaded directly into the registry, we have access to the image as what is known as an Image Stream, a project-specific view of that image.

The drop-down menus that appears will give you quick and easy access to the image we uploaded earlier. As Figure 4 shows, my project is utherp0-dev, the name I chose to upload it under was quickquarkus, and I was lazy enough to use just :latest.

Give it an appropriate application name (for cosmetic grouping in the Topology view) and a sensible name for deployment (all of the OpenShift objects created will have this name).

What's nice here is that you can then choose what kind of deployment to use. For instance, the Developer Sandbox has serverless installed, so you can deploy it as a serverless component (and you should, because it is fun). When you're ready, hit Create.

And there we have it. The application you scaffolded (hopefully) five minutes ago from the Quarkus website is now running as a serverless component on the Developer Sandbox.

Test the application

Test it out by clicking the Route icon at the top right of the roundel. This route will display the standard Quarkus landing page (Quarkus uses a scaffolded main function to generate this).

To see your RESTful endpoints, click the URL bar, change the https to http, and add /hello/subdir to the end of the URL. You should see the system time appear in the browser window along with the code changes you just made.

Final thoughts

As mentioned, there are many other ways you could approach this exercise:

• Upload the image directly using the OpenShift extension in Podman Desktop.
• Deploy directly from the Quarkus source and tools using the three different mechanisms explained earlier.
• Create the scaffolded code from the Quarkus website, add it to a Git repository, and then use the brilliant Red Hat OpenShift Dev Spaces IDE in the Developer Sandbox to edit, commit, and deploy the code right there and then.
• Automatically set up a build to rebuild and redeploy when the code changes using Tekton Pipelines and a webhook from the Git repo.
• Deploy Kubernetes objects containing your image using Argo CD.

That's the cool thing about all this tech; there are many interesting and clever ways to do it. Hopefully this activity has given you an easy and quick way to get started.