Bootstrapping Your Microservices Architecture with JHipster and Spring

Julien Dubois is the lead developer of JHipster, a Yeoman generator for Spring and AngularJS applications. Julien’s here to show how you can use a generator like JHipster to address some of the design concerns microservices introduce like discovery and routing so you can focus on your core business logic.

What is JHipster?

JHipster (for Java Hipster) is an Open Source application generator, based on Yeoman. It generates a Spring Boot (that's the Java part) and AngularJS (that's the hipster part) application, with tooling and configuration all set up for you. In this post, you’ll learn how you can use JHipster to generate a microservices stack to address design concerns like service registration, configuration and client side routing. Developers use JHipster to get their project started very quickly, with a full-stack application ready to run in production within a few minutes.

The generated application is full of best practices, tips and tooling: for example it includes BrowserSync (for client-side “live reload” of your application), Spring Boot Devtools (for “hot reload” of your Java code) and Liquibase (for automatic migration of your database schema). Used together consistently, those 3 tools make your development workflow much more efficient than what Java developers traditionally experience.

With more than 200 contributors and 200,000 downloads, JHipster is currently the most popular Java application generator, and it has reached its 3.0 version last month, focusing on microservices using the Spring Cloud Netflix stack.

JHipster microservice architecture overview

JHipster can generate classical, “monolithic” applications, and then deploy them easily on Heroku. In fact, the JHipster Heroku sub-generator is maintained by Joe Kutner (from Heroku), and is currently the most popular option for deploying JHipster applications on the cloud.

Since JHipster 3.0, the generator can also provide a full microservice architecture, based on the Spring Cloud Netflix stack. This architecture is a decoupling of the original “monolithic” application into three components:

• The JHipster Registry, which acts as a central service registry and configuration hub for the whole architecture
• Microservices applications, which are small Spring Boot applications with no user interface
• Gateway applications, which handle the front-end AngularJS code, and act as routers and load-balancers in front of the microservices applications.

A detailed explanation of all those components can be found on the JHipster microservices documentation.

Launching the JHipster Registry

JHipster uses the "JHipster Registry" to manage microservices and gateways. It is in fact two components working together:

• A Spring Cloud Netflix Eureka server used to discover all services instances
• A Spring Cloud Config server, so all nodes can be automatically configured from a central location

This JHipster Registry is a fully Open Source, Apache 2-licensed software, that you can easily install yourself. The great news with Heroku is that we have already configured it for you, and you just need to click on the button below to start your own JHipster Registry:

This will start a basic JHipster Registry, which is enough to get started and develop microservices with JHipster. You can find more information about it on the JHipster Heroku documentation.

If you haven’t done it yet, click on that button, and add a JHipster Registry to your Heroku applications. Now you can create a microservice that connects itself with the Registry.

Building a microservice with JHipster

With JHipster installed, run the following command to start a new project

yo jhipster

The generator will prompt you with a number of questions that determine how your application will be built. For the first question, the application type, choose a "microservice application". For the remaining questions, consider the following suggestions:

• Our main recommendation is to use a PostgreSQL database, as it comes bundled with Heroku.
• You can choose to use a Hibernate 2nd-level cache, but be warned this cache will not work in a distributed mode with Heroku, as the required network ports will not be opened. In the future, JHipster should support Memcached, which would be a better solution for Heroku.
• If you want to use non-default configurations or services, please verify they work correctly with Heroku. For example, if you select Elasticsearch, you need to have this service available in your Heroku space.

Once you have created your application, you can create a simple "Demo" entity by typing:

yo jhipster:entity Demo

You can give your entity a few default fields, as well as some validation rules. Those fields and rules will be applied on your AngularJS code, on your Java code (using Bean Validation for the validation rules), and on your database schema.

If you want to make complex entities, and use relationships between your entities, we highly recommend you try out JHipster’s online JDL Studio tool, that will help you create your entities graphically.

Once you have finished, use Maven to test your application. As JHipster has configured a Maven wrapper at the root of your project, this is just a matter of running:

./mvnw test

Instead of running the service locally first, we’ll deploy it on Heroku.

Deploying the microservice

The generated microservice has a Spring Boot configuration that should be already tuned for Heroku. This configuration could be automatically applied from the JHipster Registry: as the registry is also a Spring Cloud Config server, it can push configuration properties to all registered service.

Using the JHipster Registry is normally the preferred option for JHipster, but as we discussed earlier we have a basic setup, which is not secured, so we are not going to use it.

Open up your microservice application with your favorite IDE, and modify the following file:

src/main/resources/config/application-prod.yml

Edit the eureka.instance properties, so it points to your microservice application name, and doesn’t use the application’s IP address (as they are not available outside of Heroku):

eureka:
    instance:
        hostname: my-jhipster-demo.herokuapp.com
        non-secure-port: 80
        prefer-ip-address: false

The microservice hostname is the name on which your application will be deployed on Heroku.

Now your microservice is ready to connect to the JHipster Registry, once it will be deployed on Heroku.

At the root of the microservice project, run:

yo jhipster:heroku

This command will ask a few basic questions, in order to configure and deploy the microservice on Heroku. One question will ask for the location of the JHipster Registry. For this, provide the URL of your Registry in the form http://my-jhipster-registry.herokuapp.com/ (again replacing my-jhipster-registry with your Registry app name).

Once your application is deployed, go to your JHipster Registry in order to see that your microservice has been registered. For example, it should be listed in the registered services in http://my-jhipster-registry.herokuapp.com/.

Building a gateway

Once the microservice is up and running, we need to build a gateway to access it. To generate the gateway, create a new project and run again:

yo jhipster

Now you need to select "microservice gateway" as application type, and once again use a PostgreSQL database, with no Hibernate 2nd level cache, as it will be easier to deploy on Heroku.

Once this "gateway" is generated, you need to add an AngularJS-based graphical user interface, to access our previous "Demo" entity from the microservice.

In your gateway application, please run:

yo jhipster:entity Demo

As you are running this command in a gateway, JHipster will ask a new question: "Do you want to generate this entity from an existing microservice?". Answer "yes" to that question, and then point to your microservice project, so that the generator can generate a front-end code on the gateway, based on the microservice back-end.

You can now run ./mvnw test to test your Java application, and gulp test to test your JavaScript front-end.

Deploying the gateway

Exactly like we did for the microservice, we need to configure the gateway so that it uses the JHipster Registry.

Re-configure the bootstrap-prod.yml and application-prod.yml files like you did for the microservice. Don’t forget that eureka.instance.hostname must point to your application’s host name.

Again, at the root of the gateway project, run:

yo jhipster:heroku

Then run this command to set the gateway's heap size and stack size:

heroku config:set JAVA_TOOL_OPTIONS="-Xmx256m -Xss512k"

This will allow more room for off-heap memory and metaspace.

Once the gateway is started, this gateway should also get automatically registered in the JHipster Registry.

Testing the whole microservice infrastructure

Everything is now deployed! You can check that each application launched correctly by using heroku logs --tail in each application.

Connecting to the JHipster Registry, you should be able to see the demo application and the gateway application registered. For example, you could go to http://my-jhipster-registry.herokuapp.com/ to have access to the registry’s admin dashboard.

Access the gateway, for example at http://my-jhipster-gateway.herokuapp.com/ to see the whole architecture in action:

• Use the default JHipster admin account, with the default admin password
• In the Administration > Gateway menu, you should have access to a dashboard showing that the demo microservice is up. This information comes from the JHipster Registry, which is used by the gateway to automatically open up a route to that service.
• Now go to the Entities > Demo menu, in order to use the “Demo” entity, which is managed in the back-end by the microservice. You can add, update, delete and list entities from the gateway UI.

Going further

The JHipster Registry we have used here is just a basic setup: in production, it must be secured, mainly because it can contain your applications’ properties. This would allow you to have a much easier and much more secure setup.

As your application grows, this architecture will allow you to create new microservices, and maybe also more gateways (it is common to have specific gateways for different use cases). The JHipster and Heroku combo makes it very quick and easy to generate a new service, host it, and make it available on a gateway.

Once you have everything up and running, if you have any improvements to make to this setup, don’t hesitate to participate in the JHipster project. It is hosted on GitHub, and the community is always happy to have new members joining the team!

Dive in and get more information about building Spring Boot applications on Heroku.

Learn more about the support for Java and other JVM languages on Heroku.