The barriers to being an effective software architect have come down. JHipster has simplified the steps to getting a software project off to a good start with standardized methods and best practices built in. JHipster is a great tool to generate an integrated scaffolding. This blog goes over a particular set: Open APi (swagger), Spring Boot, Angular, and docker-compose.

Jhipster is a generator of [Yeoman] (https://yeoman.io/learning/) which is built on from [npm] (https://www.npmjs.com/). So, you need a linux dev environment. I’m using Ubuntu (version 18.10) for Windows. Jhipster is stable with Java 8 on Ubuntu 16.04. I assume that Java 11 on Ubuntu 18.10 will be the next stable point. The linux version is not important, but the Java version is important. Here is an example of checking java and changing it from Java 11 to Java 8. Note this is a global change of the default version.

java -version
openjdk version "11.0.1" 2018-10-16
OpenJDK Runtime Environment (build 11.0.1+13-Ubuntu-2ubuntu1)
OpenJDK 64-Bit Server VM (build 11.0.1+13-Ubuntu-2ubuntu1, mixed mode, sharing)

sudo apt-get install openjdk-8-jdk

ls -l /etc/alternatives/java
lrwxrwxrwx 1 root root 43 Oct 31 15:20 /etc/alternatives/java -> /usr/lib/jvm/java-11-openjdk-amd64/bin/java

sudo update-java-alternatives --list
java-1.11.0-openjdk-amd64      1111       /usr/lib/jvm/java-1.11.0-openjdk-amd64
java-1.8.0-openjdk-amd64       1081       /usr/lib/jvm/java-1.8.0-openjdk-amd64

sudo update-java-alternatives --set java-1.8.0-openjdk-amd64

java -version
openjdk version "1.8.0_181"
OpenJDK Runtime Environment (build 1.8.0_181-8u181-b13-1ubuntu0.18.10.1-b13)
OpenJDK 64-Bit Server VM (build 25.181-b13, mixed mode)

In this guide I’m useing jhipster via ubuntu for windows (Ubuntu version 18.10 but 18.04 and 16.04 also have worked for me). To use just type jhipster and it will create your files in your current directory based on your menu choices. By default it uses a series of command line menus to initialize your Application.

There are 4 types of Applications that can be generated.

Monolithic application (recommended for simple projects)
Microservice application
Microservice gateway
JHipster UAA server (for microservice OAuth2 authentication)

During the execution of the jhipster command, it will also give instruction to any maintenance commands that should be run outside of the application.

Here are some example messages.

 ️⚠️  WARNING ⚠️  You are in your HOME folder!
 This can cause problems, you should always create a new directory and run the jhipster command from here.
 See the troubleshooting section at https://www.jhipster.tech/installation/

 _______________________________________________________________________________________________________________

  Documentation for creating an application is at https://www.jhipster.tech/creating-an-app/
  If you find JHipster useful, consider sponsoring the project at https://opencollective.com/generator-jhipster
 _______________________________________________________________________________________________________________

 WARNING! Java 1.8 is not found on your computer. Your Java version is: 11.0.1

 ______________________________________________________________________________

  JHipster update available: 5.7.1 (current: 5.3.4)

  Run `npm install -g generator-jhipster` to update.

 ______________________________________________________________________________

   ╭───────────────────────────────────────────────────────────────╮
   │                                                               │
   │       New minor version of npm available! 6.4.1 → 6.5.0       │
   │   Changelog: https://github.com/npm/cli/releases/tag/v6.5.0   │
   │               Run npm install -g npm to update!               │
   │                                                               │
   ╰───────────────────────────────────────────────────────────────╯

Monolithic application

Skip this if you want to split everything up.

You can use JHipster Registry to configure, monitor and scale your application. (default is no)

There are three type of authentication to use.

❯ JWT authentication (stateless, with a token)
OAuth 2.0 / OIDC Authentication (stateful, works with Keycloak and Okta)
HTTP Session Authentication (stateful, default Spring Security mechanism)

Note: no UAA option in mono app.

There are three type of database to use.

❯ SQL (H2, MySQL, MariaDB, PostgreSQL, Oracle, MSSQL)
MongoDB
Couchbase

Note: no Cassandra in mono app.

Note: the type of database will affect the behavoir of the models. For example, you cannot configure relationships if you choose MongoDB since it is a NoSQL database.

There are five options for spring cache abstraction

Yes, with the Ehcache implementation (local cache, for a single node)
❯ Yes, with the Hazelcast implementation (distributed cache, for multiple nodes)
[BETA] Yes, with the Infinispan implementation (hybrid cache, for multiple nodes)
Yes, with Memcached (distributed cache) - Warning, when using an SQL database, this will disable the Hibernate 2nd level cache!
No - Warning, when using an SQL database, this will disable the Hibernate 2nd level cache!

There are two options for building the backend

❯ Maven
Gradle

There are four other technologies to add

❯◯ Search engine using Elasticsearch
◯ WebSockets using Spring Websocket
◯ Asynchronous messages using Apache Kafka
◯ API first development using OpenAPI-generator

There are two Framework to use for the client.

❯ Angular
React

You can enable SASS stylesheet preprocessor. (Yes by default). See UI customize section.

Besides JUnit and Jest, there are three testing frameworks to use.

❯◯ Gatling
◯ Cucumber
◯ Protractor

JHipster UAA server

The UAA server has three options for service discovery.

❯ JHipster Registry (uses Eureka, provides Spring Cloud Config support and monitoring dashboards)
Consul
No service discovery

There are four options for databases to use.

❯ SQL (H2, MySQL, MariaDB, PostgreSQL, Oracle, MSSQL)
MongoDB
Couchbase
Cassandra

Note: the type of database will affect the behavoir of the models. For example, you cannot configure relationships if you choose MongoDB since it is a NoSQL database.

There are five options for spring cache abstraction

Yes, with the Ehcache implementation (local cache, for a single node)
❯ Yes, with the Hazelcast implementation (distributed cache, for multiple nodes)
[BETA] Yes, with the Infinispan implementation (hybrid cache, for multiple nodes)
Yes, with Memcached (distributed cache) - Warning, when using an SQL database, this will disable the Hibernate 2nd level cache!
No - Warning, when using an SQL database, this will disable the Hibernate 2nd level cache!

There are two options for building the backend

❯ Maven
Gradle

There are three other technologies to add

❯◯ Search engine using Elasticsearch
◯ Asynchronous messages using Apache Kafka
◯ API first development using OpenAPI-generator

You can add support for 41 internationalizations

Albanian
Arabic (Libya)
Armenian
Belorussian
Bengali
Catalan
Chinese (Simplified)
Chinese (Traditional)
Czech
Danish
Dutch
English
Estonian
Farsi
French
Galician
German
Greek
Hindi
Hungarian
Indonesian
Italian
Japanese
Korean
Marathi
Myanmar
Polish
Portuguese (Brazilian)
Portuguese
Romanian
Russian
Slovak
Serbian
Spanish
Swedish
Turkish
Tamil
Thai
Ukrainian
Uzbek (latin)
Vietnamese

Besides JUnit, there are two optional testing frameworks to use

❯◯ Gatling
◯ Cucumber

You can install 21 other generators from the JHipster Marketplace (default is no)

◯ (generator-jhipster-nav-element-2.1.0) A generator to scaffold a new page (and the corresponding navigation menu) in a JHipster project.
◯ (generator-jhipster-vuejs2-0.4.79) jHipster generator for vuejs client side
◯ (generator-jhipster-primeng-charts-1.2.0) Generate sample charts with PrimeNG
◯ (generator-jhipster-primeng-2.1.0) Generate PrimeNG Components
◯ (generator-jhipster-docker-2.5.0) Additional Docker support: Docker Hub, Local SMTP Server, NGinx
◯ (generator-jhipster-spring-cloud-stream-1.0.0) JHipster module for messaging microservices with Spring Cloud Stream
◯ (generator-jhipster-standalone-profile-2.2.0) Add standalone profile to Jhipster application
◯ (generator-jhipster-swagger-cli-3.0.1) JHipster module to generate swagger client code from a swagger definition
◯ (generator-jhipster-electron-1.0.0) A jhipster module to run spring boot app in electron package
◯ (generator-jhipster-leafletmap-2.0.0) This module generates a leaflet map in a new page of a monolithic and Angular 5 jhipster application (4.14.1).
◯ (generator-jhipster-audit-helper-1.0.3) JHipster module to enable entity audit
◯ (generator-jhipster-obfuscation-at-rest-0.3.0) JHipster module for creating data obfuscation at rest (only JPA support)
◯ (generator-codegen-0.2.1) Yeoman generator to scaffold new generators
◯ (generator-jhipster-uaa-security-authority-1.0.1) A JHipster module that create uaa security authority restful resource for communication between uaa and microservices
◯ (generator-jhipster-feign-client-1.0.6) JHipster module for create feign client with entity for communication between two microservices
◯ (generator-jhipster-social-login-api-0.0.1) Adds social login api calls to work with native Android and iOS apps from android-jhi generator
◯ (generator-jhipster-vmware-clarity-1.1.1) A JHipster module that create VMWare Clarity Design UI framework for Angular client.
◯ (generator-jhipster-cockroachdb-0.0.10) Jhipster CockroachDB
◯ (generator-jhipster-vuejsx-0.0.1) jHipster generator for vuejs client side
◯ (generator-jhipster-file2url-0.0.0) add file entity save with url
◯ (generator-jhipster-aeropost-1.6.0) Add Scheduler Lock

After navigating the menuoptions, the application will execute the following items:

create a local git repo
extract the node_modules folder for staging
add the files
commit the files to git

Installing generator-jhipster@5.7.1 locally using npm
[            ......] \ extract:lodash: sill extract lodash@4.17.11

If you chose maven, the application will finish with the something like the following

npm notice created a lockfile as package-lock.json. You should commit this file.
added 511 packages from 331 contributors and audited 3747 packages in 106.25s
found 0 vulnerabilities

Application successfully committed to Git.

If you find JHipster useful consider sponsoring the project https://www.jhipster.tech/sponsors/

Server application generated successfully.

Run your Spring Boot application:
./mvnw
INFO! Congratulations, JHipster execution is complete!

starting a maven application

Type ./mvnw to build and launch the default application

If Java 8 is not installed you will see this error

[WARNING] Rule 1: org.apache.maven.plugins.enforcer.RequireJavaVersion failed with message:
You are running an incompatible version of Java. JHipster requires JDK 1.8

This will probably fail if you do not have the external services (like mongoDB and jhipster-registery) already running on default ports locally.

If everything starts, you will see this in the logs.

----------------------------------------------------------
        Application 'weather' is running! Access URLs:
        Local:          http://localhost:9999/weather
        External:       http://127.0.1.1:9999/weather
        Profile(s):     [dev, swagger]
----------------------------------------------------------

jhipster-registry

This can be found on docker hub jhipster-registry. jhipster/jhipster-registry

docker run --name registry -p8761:8761 -d jhipster/jhipster-registry; docker logs -f registry
----------------------------------------------------------
        Application 'jhipster-registry' is running! Access URLs:
        Local:          http://localhost:8761
        External:       http://172.17.0.3:8761
        Profile(s):     [prod, composite]
----------------------------------------------------------

mongo

This can be found on docker hub mongo

sudo apt install docker.io
docker run --name mongo -p 27017:27017 -d mongo

mysql

This can be found on docker hub mySQL

sudo apt install docker.io
docker run mysql

Microservice gateway

After you have created the UAA, if you choose to create a Microservice gateway the following describes the options.

Three service discovery server options

❯ JHipster Registry (uses Eureka, provides Spring Cloud Config support and monitoring dashboards)
Consul
No service discovery

Three type of authentication to use

JWT authentication (stateless, with a token)
OAuth 2.0 / OIDC Authentication (stateful, works with Keycloak and Okta)
❯ Authentication with JHipster UAA server (the server must be generated separately)

Two Framework to use for the client

❯ Angular
React

You can enable SASS stylesheet preprocessor (default is yes)

Besides JUnit and Jest, there are three testing frameworks to use

❯◯ Gatling
◯ Cucumber
◯ Protractor

After creating the files, you will see

I'm all done. Running npm install for you to install the required dependencies. If this fails, try running the command yourself.

                                        Thanks for installing ngx-infinite-scroll
                                     Please consider donating to our open collective
                                            to help us maintain this package.

                                                Number of contributors: 23
                                                   Number of backers: 5
                                                    Annual budget: $82
                                                   Current balance: $78

                           Donate: https://opencollective.com/ngx-infinite-scroll/donate
added 1826 packages from 1031 contributors and audited 60816 packages in 465.921s
found 8 low severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details
Application successfully committed to Git.

If you find JHipster useful consider sponsoring the project https://www.jhipster.tech/sponsors/

Server application generated successfully.

Run your Spring Boot application:
./mvnw

Client application generated successfully.

Start your Webpack development server with:
 npm start

Here are some common warnings when creating a gateway.

npm WARN deprecated swagger-ui@2.2.10: No longer maintained, please upgrade to swagger-ui@3.

npm WARN ng-jhipster@0.5.6 requires a peer of @angular/core@^6.0.0 but none is installed. You must install peer dependencies yourself.

npm WARN ng-jhipster@0.5.6 requires a peer of @angular/router@^6.0.0 but none is installed. You must install peer dependencies yourself.

npm WARN bootstrap@4.1.3 requires a peer of jquery@1.9.1 - 3 but none is installed. You must install peer dependencies yourself.

npm WARN bootstrap@4.1.3 requires a peer of popper.js@^1.14.3 but none is installed. You must install peer dependencies yourself.

npm WARN ngx-webstorage@2.0.1 requires a peer of @angular/core@^5.0.0 but none is installed. You must install peer dependencies yourself.

npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.2.4 (node_modules/fsevents):

npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@1.2.4: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})

For these warnings check package.json and re-run npm install. You can normally ignore version mismatch. But not missing ones altogether. Iterate over these commands until there are no vulnerabilities

npm audit
npm audit fix
vi packages.json
npm install

Launch the gateway

Use the ./mvnw command to build and launch the gateway. At this point it is just an default gateway that is using your UAA.

----------------------------------------------------------
        Application 'gateway' is running! Access URLs:
        Local:          http://localhost:8080/
        External:       http://127.0.1.1:8080/
        Profile(s):     [dev, swagger]
----------------------------------------------------------

Make sure the UAA is running before running the gateway. Otherwise, new user regirstration will fail.

The UAA will try to send an email with something like the following

<html>
    <head>
        <title>uaa account activation</title>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
        <link rel="shortcut icon" href="http://127.0.0.1:8080/favicon.ico" />
    </head>
    <body>
        <p>Dear newuser</p>
        <p>Your uaa account has been created, please click on the URL below to activate it:</p>
        <p>
            <a href="http://127.0.0.1:8080/#/activate?key=00703500715244874438">http://127.0.0.1:8080/#/activate?key=00703500715244874438</a>
        </p>
        <p>
            <span>Regards,</span>
            <br/>
            <em>uaa Team.</em>
        </p>
    </body>
</html>

You will see and error in the logs if no email service is configured on the uaa host machine.

At this point you have the basic system up and running. You cando all of that “user management” stuff.

Create a Microservice application

Next you will want to add a microservice to your system to do something.

Type jhipster in a new directory and follow the menu.

Create an entity

jhipster entity team

If you create the entity, you can copy it to the gateway and other microservices.

Customize the UI

I’m still researching this area and have been hitting a lot of error in 18.10

You can use a CSS Authoring Framework like Compass install which uses a Ruby environment.

Install the correct ruby files.

sudo apt-get install ruby`ruby -e 'puts RUBY_VERSION[/\d+\.\d+/]'`-dev

Now install compass via gem using the command sudo gem install compass

sudo gem install compass
Successfully installed ffi-1.9.25
Fetching: rb-inotify-0.10.0.gem (100%)
Successfully installed rb-inotify-0.10.0
Fetching: compass-1.0.3.gem (100%)
    Compass is charityware. If you love it, please donate on our behalf at http://umdf.org/compass Thanks!
Successfully installed compass-1.0.3
Parsing documentation for ffi-1.9.25
Installing ri documentation for ffi-1.9.25
Parsing documentation for rb-inotify-0.10.0
Installing ri documentation for rb-inotify-0.10.0
Parsing documentation for compass-1.0.3
Installing ri documentation for compass-1.0.3
Done installing documentation for ffi, rb-inotify, compass after 19 seconds
3 gems installed

After compass is installed, run it using the compass create command.

compass create weather
directory weather/
directory weather/sass/
directory weather/stylesheets/
   create weather/config.rb
   create weather/sass/screen.scss
   create weather/sass/print.scss
   create weather/sass/ie.scss
    write weather/stylesheets/ie.css
    write weather/stylesheets/print.css
    write weather/stylesheets/screen.css

*********************************************************************
Congratulations! Your compass project has been created.

You may now add and edit sass stylesheets in the sass subdirectory of your project.

Sass files beginning with an underscore are called partials and won't be
compiled to CSS, but they can be imported into other sass stylesheets.

You can configure your project by editing the config.rb configuration file.

You must compile your sass stylesheets into CSS when they change.
This can be done in one of the following ways:
  1. To compile on demand:
     compass compile [path/to/project]
  2. To monitor your project for changes and automatically recompile:
     compass watch [path/to/project]

More Resources:
  * Website: http://compass-style.org/
  * Sass: http://sass-lang.com
  * Community: http://groups.google.com/group/compass-users/


To import your new stylesheets add the following lines of HTML (or equivalent) to your webpage:
<head>
  <link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet" type="text/css" />
  <link href="/stylesheets/print.css" media="print" rel="stylesheet" type="text/css" />
  <!--[if IE]>
      <link href="/stylesheets/ie.css" media="screen, projection" rel="stylesheet" type="text/css" />
  <![endif]-->
</head>

Use a docker container

After you have you system working from maven, you will want to build a docker-compose.yml file to configure and run all of the containers.

See docker-compose instructions for more info.

After you have an application up and running, you will want to create some entities. Entities are the models used in the microservices and databases.

Using JHipster to build your project scaffolding