Deploy Java Like a Pro: Your First Quarkus App on OpenShift in Minutes

A fun, hands-on guide for Java developers to build a REST API with Quarkus, PostgreSQL, and deploy it to OpenShift Developer Sandbox with no Kubernetes expertise required.

If you're diving into the world of cloud-native Java development, Quarkus is your new best friend. Built for Kubernetes, this lightweight, lightning-fast Java stack transforms the way we think about Java. Today, you'll become a Quarkus hero by creating a simple REST API, connecting it to PostgreSQL using Hibernate ORM with Panache, and deploying it to Red Hat's OpenShift Developer Sandbox. All in one go and under 15 minutes!

Setting Up the Hero's Workshop

Step 1: Install the Necessary Tools

First, let's gather your gear. You'll need:

• Java (preferably JDK 17+)

• Maven

• Quarkus CLI

• Optional: For macOS, you can install the OpenShift CLI (oc) by using the Homebrew package manager.

Install the Quarkus CLI with SDKMAN!:

sdk install quarkus

Verify your setup:

quarkus --version

If you are on MacOS, you can easily install the OpenShift CLI. This step is optional, we will be using a token and server URL in the tutorial below.

brew install openshift-cli

Step 2: Bootstrapping Your Quarkus Adventure

Create a new Quarkus project directly from your terminal:

quarkus create app com.example:hero-api \
    --extension=quarkus-rest-jackson,quarkus-hibernate-orm-panache,quarkus-jdbc-postgresql

This single command equips you with REST endpoints, Panache ORM, PostgreSQL client, and reactive goodness right out of the box.

Crafting Your RESTful Hero

Navigate to your new Quarkus adventure:

cd hero-api

Step 3: Create the Hero Entity

Your hero needs identity and character. Let’s refactor the com.example.MyEntity to a hero:

package com.example;

import io.quarkus.hibernate.reactive.panache.PanacheEntity;
import jakarta.persistence.Entity;

@Entity
public class Hero extends PanacheEntity {
    public String name;
    public String superPower;
}

Quarkus uses Panache to simplify database interactions. Think of Panache as the helpful sidekick that handles the boring stuff so you can focus on your mission.

Step 4: REST Endpoint to the Rescue

Add a REST endpoint to manage your heroes. Let’s refactor the GreetingResource to a HeroResource:

package com.example;

import java.net.URI;
import java.util.List;
import jakarta.transaction.Transactional;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/heroes")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class HeroResource {

    @GET
    public List<Hero> list() {
        return Hero.listAll();
    }

    @POST
    @Transactional
    public Response add(Hero hero) {
       hero.persist();
        return Response.created(URI.create("/heroes/" + hero.id))
           .build();
    }
}

Simple and effective. Your REST API can now list and add heroes.

Configure Your Hero’s Database

Before running your app, let's configure PostgreSQL. Quarkus makes this straightforward:

Step 5: Configuration in application.properties

Edit your application.properties file:

quarkus.datasource.db-kind=postgresql
quarkus.hibernate-orm.database.generation=drop-and-create

In a local development setup, drop-and-create ensures your database schema always matches your entities. A lifesaver during active development.

Step 6: Delete the tests

Yes. I know. BUT :)

Running Locally Before Flying to the Cloud

When running Quarkus in development mode, Dev Services automatically spins up a PostgreSQL instance for you; no manual configuration needed! As long as you have Docker or Podman installed, Quarkus takes care of everything behind the scenes.

Step 7: Run and Test Your App Locally

Fire up your Quarkus app in dev mode:

quarkus dev

Visit http://localhost:8080/heroes. You should see an empty list. Let's add a hero:

curl -X POST -H "Content-Type: application/json" -d '{"name":"Quarkus Hero", "superPower":"Fast startup"}' http://localhost:8080/heroes

Revisit the list, and voilà, your hero appears!

Deploying to OpenShift Developer Sandbox

Now it's time to take your hero to the skies of OpenShift!

Step 8: Sign Up and Log in to OpenShift Sandbox

Head to OpenShift Developer Sandbox and create your free account. The Sandbox will be available for next 30 days. No strings attached. No credit card. Just play around. Jump right in and start creating your applications! You are already logged in and you can “launch” OpenShift. Just click the “Login with Sandbox” button and you’re taken directly to the Web-Console.

Step 9: Configure for OpenShift Deployment

If you havent, stopp your dev mode locally and add OpenShift extensions to your Quarkus project:

quarkus extension add openshift

After we added the extension, we need to make sure it can do it’s magic. Let’s add some more lines to the application.properties:

quarkus.kubernetes.deployment-target=openshift

quarkus.openshift.route.expose=true
quarkus.openshift.route.target-port=http
quarkus.openshift.route.tls.termination=edge

quarkus.kubernetes-client.api-server-url=https://api.<XX>.<XX>.<XX>.openshiftapps.com:6443
quarkus.kubernetes-client.token=<YOUR_TOKEN>

The deployment target is pretty self-explanatory. The route properties are necessary to make sure the TLS request is terminated at the ingress and redirected to the Quarkus applications which runs on http.

You get the api-server-URL and the Token from the OpenShift Sandbox Web Console, if you navigate to the top right and expand the little arrow under your username it gives you an option to “Copy Login Command” which redirects you to a page with the token and url details.

So far, we have not configured anything specifically for the database. If we want to use an external one on Kubernetes or OpenShift, we will have to tell Quarkus where to find it and how to access it. This is also done in the application.properties:

quarkus.kubernetes.env.configmaps=postgresql-datasource-props
quarkus.datasource.username=${POSTGRESQL_USER}
quarkus.datasource.password=${POSTGRESQL_PASSWORD}
quarkus.datasource.jdbc.url=${POSTGRESQL_URL}

The properties are mapped against environment variables. We do need to make the environment variables available to the Quarkus application. And this is done via ConfigMaps in Kubernetes. And yes, you already spotted the quarkus.kubernetes.env.configmaps property above. A Kubernetes ConfigMap is an object used to store non-sensitive configuration data as key-value pairs, allowing you to decouple configuration from application code. We need to get the ConfigMap definition into the Quarkus OpenShift deployment information. And this is done by creating an additional folder under src/main/ named kubernetes.

Add the following information into a file called common.xml

apiVersion: v1
kind: ConfigMap
metadata:
  name: postgresql-datasource-props
data:
  POSTGRESQL_URL: "jdbc:postgresql://postgresql:5432/example"
  POSTGRESQL_USER: "user"
  POSTGRESQL_PASSWORD: "pass"

The content of the file is added to target/kubernetes/openshift.yaml during the augmentation phase and deployed together with the application.

Step 10: Deploy PostgreSQL Database on OpenShift

In your sandbox web console:

• Navigate to Developer > Add > <your_project> Developer Catalog > Database

• Select PostgreSQL (Ephemeral) and click “Instantiate Template”

• Let’s change some things:

  • PostgreSQL Connection Username: “user”

  • PostgreSQL Connection Password: “pass”

  • PostgreSQL Database Name: “example”

  • Version of PostgreSQL Image: “latest”

PLEASE do not use explicit username/password combinations in production. I am taking a shortcut here to keep the article at a manageable size for beginners. You should absolutely externalise them. And you already guessed: Exactly, with environment variables mapped to a ConfigMap.

• Click the blue “Create” button at the bottom of the page.

After a few seconds your database instance is up and running.

Step 11: Deploy Your Quarkus Application

Run:

quarkus build 
quarkus deploy openshift

Quarkus automates container building and deployment directly to your OpenShift Sandbox.

Step 12: Watch Your Hero Take Flight

Back in OpenShift's developer console, watch as your app deploys on the topology view. Once deployed, click your application's route URL (the little arrow on top of the hero-api pod!

Visit https://YOUR_APP_URL/heroes to see your REST endpoint live on OpenShift!

And you can of course add a hero here too:

curl -X POST -H "Content-Type: application/json" -d '{"name":"Quarkus Hero", "superPower":"Fast startup"}' https://YOUR_APP_URL/heroes

Make sure you are hitting the TLS/Https endpoint!

Your Hero's Journey Has Just Begun

You've successfully created, containerized, and deployed a Quarkus application to the cloud. You've handled REST APIs, ORM with Panache, PostgreSQL databases, and Kubernetes deployment which are all foundational skills for the modern Java developer.

If you want to know more about the Quarkus OpenShift or Kubernetes extension, take a look at this extensive guide.

Quarkus and OpenShift aren't just powerful technologies; they're fun to work with. Go forth, experiment more, and build even cooler apps. After all, every hero deserves sequels!