Spring Boot and JHipster With Reactive Microservices?


Learn how to create a reactive microservices architecture with Spring Boot, Spring Cloud Gateway, Spring Cloud Config, Spring WebFlux, Java, and JHipster.

Spring Boot and JHipster With Reactive Microservices?
Spring Cloud Gateway, Spring Cloud Config, Spring WebFlux, Java, and JHipster

Even though it only came to prominence a few years ago, Java has been at the forefront of microservice architecture. Spring Cloud, Spring Data, and Spring Security, Java are well-known high-quality frameworks.

Spring WebFlux is a new web framework introduced by Spring Boot 2.0. While previous versions of Spring Boot only shipped with Spring MVC as an option, WebFlux gives the developers the chance to do reactive programming, meaning you can write your code with familiar syntax. As a result, your app will scale better and use up fewer resources.

Spring WebFlux vs Spring MVC
Spring WebFlux vs Spring MVC

Why Reactive Microservices?

Reactive programming isn’t for every app. The general rule of thumb is it won’t help you if you have < 500 requests/second. Chances are Spring MVC will perform as well as Spring WebFlux up to that point. When your traffic takes off, or if you need to process things faster than 500 requests/second, you should take a look at Spring WebFlux.

Spring WebFlux’s API has a similar syntax to Spring MVC. For example, here’s the Spring MVC code for creating a new Points entity.

The same functionality when implemented with Spring WebFlux returns a Mono and uses a more functional, streaming style to avoid blocking.

In this guide, I’ll show you how to create a reactive microservices architecture with Spring Boot, Spring Cloud Gateway, Spring Cloud Config, Spring WebFlux, Java, and JHipster.

Reactive Java Microservices
Reactive Java Microservices


You can find the completed source code for this example on GitHub, in the oktadeveloper/java-microservices-examples repository.

Build a Reactive Microservices Architecture

JHipster is an open-source project that started as an application generator, based on Yeoman. It’s also the most popular Yeoman generator. JHipster initially allowed you to generate AngularJS and Spring apps. In the last five years, it’s become a platform with extensibility, grown a thriving community, and has saved developers many hours of pain and frustration.

You see, JHipster integrates everything for you. Do you want to use Angular with Spring Boot? It’s got that. React? Yep. Microservices with Spring Cloud? Check!

In this tutorial, I’ll show you how to generate a microservice architecture that uses OAuth 2.0, an API gateway, and two microservices (a blog and a store). The gateway will use PostgreSQL with R2DBC, the blog will use Neo4j, and the store will use MongoDB. All persistence options are powered by Spring Data.

Start by installing JHipster using npm:

After installing JHipster, you can run the following command to answer a whole slew of questions and create an app.

JHipster code
JHipster code

However, there’s an easier way. JHipster has its own domain language!

Define Your Reactive Java Architecture With JDL

JHipster Domain Language (JDL) offers a way to define apps, so you don’t have to worry about fat-fingering your answer to the jhipster command’s questions.Reactive Microservices, Spring Boot and JHipster With Reactive Microservices?

Create a new directory on your machine and navigate into it in your terminal.

Copy the JDL below and put it into a reactive-ms.jdl file.

  1. The first app is an API gateway.
  2. Because the gateway is reactive, it’ll use Spring Cloud Gateway.
  3. The gateway and microservice apps must use the same authentication type.
  4. Use Gradle, because a lot of y’all love it.
  5. Vue support is new in JHipster 7, let’s use it!
  6. Make sure and specify microservice as the application type for the blog and store apps.
  7. JDL allows you to create Docker Compose and Kubernetes deployments too!

See application configuration options to see the possible values for the above configuration options.

Import this architecture definition and generate gatewayblog, and store apps.

As part of this process, several Docker Compose files are generated for you. These allow you to run databases, the JHipster Registry (for service discovery), Keycloak (for identity), all with Docker.

Run Your Reactive Java Microservices

After JHipster finishes generating your apps, you can run them with Gradle. Assuming you’re in the same top-level directories you ran jhipster jdl from, you can run the following commands to start all the backend services for each microservice.

JHipster has a Oh My ZSH! plugin that I highly recommend. It provides aliases for starting Docker containers and is a real time-saver. I’ve included these commands as comments below.

Reactive Microservices, Spring Boot and JHipster With Reactive Microservices?

The JHipster Registry is a Netflix Eureka server that handles service discovery. When the gateway and microservices start up, they register with Eureka. This allows communication between services using logical names, rather than IP address or host names. JHipster Registry also contains a Spring Cloud Config server that can distribute configuration between apps. You can learn more about Spring Cloud Config in Spring Cloud Config for Shared Microservice Configuration.

Open a new terminal window, start the blog app’s Neo4j database, and then the app itself.

Then, open another terminal window, start the store app’s MongoDB database, and the microservice.

To make Keycloak work, you need to add the following line to your hosts file (/etc/hosts on Mac/Linux, c:\Windows\System32\Drivers\etc\hosts on Windows).

This is because you will access your application with a browser on your machine (which is named localhost, or, but inside Docker, it will run in its own container, which is named keycloak.

Test Your Reactive Java Microservices

Test Your Reactive Java Microservices
Test Your Reactive Java Microservices
Java Hipster
Java Hipster

Open http://localhost:8080 in your favorite browser. You should be able to login with admin/admin as credentials.

Make sure you can add a new blog, edit existing posts, and add new products.

Reactive Stack Gateway
Reactive Stack Gateway

To prove everything works in an automated fashion, you can run npm run e2e in the gateway project’s directory. This will run a number of end-to-end tests with Protractor.JHipster has support for Cypress, but it doesn’t work with Okta yet.

Prepare Your Reactive Java Stack for Production

Keycloak is a superb open source identity provider. It has excellent support for OAuth 2.0 and OpenID Connect (OIDC) and easily runs in a Docker container. I greatly appreciate Keycloak’s ease-of-use. I also appreciate Spring Security’s OAuth and OIDC support.

Spring Security makes it so you only need to override three properties to switch from Keycloak to Okta!

In production, you might not want to manage your own identity provider instance. That’s where Okta comes in. We’re a developer-friendly SaaS company that provides OAuth and OIDC support as a service. You can create a developer account and use it for free. Our Okta CLI makes it super easy.

Install the Okta CLI using the aforementioned website and come back here when you’re done. If you don’t have an Okta developer account, run okta register.

You can also use your browser and Okta’s developer console to register an app. See JHipster’s security documentation for those instructions.

Then, from the gateway project’s directory, run okta apps create jhipster. Accept the default redirect URIs.

Okta apps create jhipster
Okta apps create jhipster

This process does several things:

  1. Registers an OIDC app in Okta with JHipster’s configured redirect URIs.
  2. Creates ROLE_ADMIN and ROLE_USER groups and adds your user to both.
  3. Creates a groups claim and adds it to ID tokens.
  4. Creates a .okta.env file with the values you’ll need to talk to Okta.

Update the JHipster Registry to Distribute OIDC Configuration

I mentioned earlier that Spring Cloud Config allows you to distribute Spring’s configuration between apps. In this section, you’ll configure JHipster’s Spring Security settings to use Okta across all your services.

Add the following YAML to gateway/src/main/docker/central-server-config/localhost-config/application.yml. You can find the values for each property in the .okta.env file.

Save your changes. These values will be distributed to the JHipster Registry, gateway, blog, and store apps. Restart the JHipster Registry by running the following commands:

Use Ctrl+C to kill all your ./gradlew processes and start them again.

Now, open a new incognito browser window, go to http://localhost:8080, and sign in. Rejoice that using Okta for authentication works!Reactive Microservices, Spring Boot and JHipster With Reactive Microservices?Reactive Microservices, Spring Boot and JHipster With Reactive Microservices?

If you’re feeling lucky, you can set your Okta credentials as environment variables and run end-to-end tests (from the gateway directory).

Your JHipster Registry is now configured to use Okta for authentication. You’ll need to add redirect URIs in your Okta app for http://localhost:8761. After making these changes, you should be able to sign in to it.

Create Docker Images for Your Microservice Apps

The JDL you used to create this reactive stack contains Docker configuration, so you can run everything with Docker Compose.

Stop all your apps with Ctrl+C. Stop all your Docker instances too.

Reactive Microservices, Spring Boot and JHipster With Reactive Microservices?

To run your reactive stack with Docker Compose, you need to create Docker images for each app. In your three different app directories, run the following Gradle command:

Run Your Microservices Stack with Docker Compose

Once your Docker containers are finished building, you’ll want to add your Okta settings to Spring Cloud Config in JHipster Registry.

Switch Identity Providers With Spring Cloud Config

Open docker-compose/docker-compose.yml in your favorite IDE (I like IntelliJ IDEA) and remove the Keycloak image at the bottom. You can leave it if you like, but it won’t be used in this example.

Update docker-compose/central-server-config/application.yml to contain your OIDC settings that you want to share with all your microservices.

Prove Your Reactive Java Stack Works

In the docker-compose directory, run the following command to start all your containers.

Reactive Microservices, Spring Boot and JHipster With Reactive Microservices?

Reactive Microservices, Spring Boot and JHipster With Reactive Microservices?

You should be able to open http://localhost:8080, sign in, and access all of your microservices. Pretty slick, eh?!

What About Kotlin Microservices?

JHipster supports Kotlin-based microservices thanks to its Kotlin blueprint.

You can install it using npm:

Then, use khipster jdl reactive-ms to create the same stack you did above with Kotlin.

Reactive Microservices, Spring Boot and JHipster With Reactive Microservices?

How Do I Deploy to the Cloud?

JHipster creates a cloud-native microservices architecture that can be deployed to many cloud providers. There’s specific support for AWS, Microsoft Azure, Heroku, and Google Cloud Platform.

However, if you’re doing microservices, you’ll probably want to leverage Docker as you did in this tutorial. When your apps are containerized, they can be orchestrated with Kubernetes.

JHipster has a Kubernetes sub-generator that you can use to deploy it to the cloud.