The Developer’s Bookshelf with Heroku

I have created a Spring Boot + Thymeleaf + Heroku Template that can be utilized for rapidly developing Spring Boot + Thymeleaf applications that are fully deployable to Heroku. In this tutorial I will show the steps involved in quickly creating a demo application utilizing this template.

 

Demo Application

I will be creating a demo application called The Developer’s Bookshelf. The source code is available on GitHub.

There is a live demo running on Heroku, but keep in mind that it might take 120 seconds to load on the first request.  Please be patient with the first request. Subsequent requests will be normal.

Here is The Developer’s Bookshelf running on Heroku.

The Developer’s Bookshelf shows a list of books on the home page. Any user can view a book in more detail by clicking on it. An administrator has the capability to add, edit, and delete books. You can log in as an administrator by clicking on the Sign in button at the top right and utilizing the following credentials: ‘admin’ and ‘admin’.

The Developer's Bookshelf Home Page

 

Overview of the Steps

The following steps will be taken in order to create The Developer’s Bookshelf.

  1. Create a project with the given template
  2. Customize the application
  3. Test the application locally
  4. Test the application on Heroku
  5. Create a JHipster version 2.6.0 application
  6. Generate entities and changelogs with JHipster
  7. Transfer entities and changelogs to the template project
  8. Customize entities and changelogs
  9. Create services, controllers, unit tests, integration tests
  10. Modify the local database
  11. Develop the application
  12. Deploy application

 

Create a project with the given template

Firstly, the Spring Boot + Thymeleaf + Heroku Template project can be cloned from GitHub into an empty directory.

This will create the ‘spring-boot-thymeleaf-heroku-template’ project folder.

Navigate into the folder and delete the hidden ‘.git’ folder so that the project is not connected to the original template on GitHub.

Create a fresh Git repository for the new project from the command line as follows:

Modify the name of the project directory with the name of your new project. In my case the name of my project will be called developer-bookshelf-heroku.

Open the project in your favourite IDE. I will be working with Eclipse for this demonstration. In Eclipse, the project can be imported as a Maven project.

 

Customize the application

The following image shows the structure of the initial template project.

Starting template

Create the following three packages in the src/main/java folder for later use.

  • com.chrisbaileydeveloper.myapp.domain
  • com.chrisbaileydeveloper.myapp.repository
  • com.chrisbaileydeveloper.myapp.service

The src/main/java folder should now appear as follows:

Template packages

Choose a project name and make the following modifications:

  1. Rename the project packages in src/main/java as well as src/test/java.
  2. Open the license file and modify it to suit your needs.
  3. Open the pom.xml.

Modify the groupId, artifactId, and version of the project. Remember not to modify anything in the <parent> element.

Search for the following text and modify the package name for your project:

  1. Delete the contents of the README.md file.
  2. Modify the DatabaseConfiguration class, contained in the src/main/java/…config package, so that the following line contains your package name:

  1. Modify the src/main/resources/logback.xml file so that the following line contains your package name:

  1. Modify the src/test/resources/logback-test.xml file so that the following line contains your package name:

 

Test the application locally

Let’s test the application locally to make sure things are set up properly.

Navigate to the project on the command line.

Navigate to http://localhost:8080.

Note that the application can also be deployed by running the Application class in the src/main/java/…myapp package.

The following home page should be displayed. Template initial page

 

Test the application on Heroku

The following steps require that the Heroku Toolbelt has been installed locally and that an Heroku account has been created.

Navigate to the project directory on the command line.

Before creating your Heroku application, make sure that you have committed your most recent changes to your Git repository.

Create a new application on Heroku.

Rename your Heroku application if interested.

Add a PostgreSQL database to your Heroku application.

Deploy the project to Heroku.

Wait for Heroku to load your application.

Look at your application logs to see what is happening behind the scenes.

If your application deploys without timing out then it can be opened as follows:

You should now see the template online being hosted on your Heroku account.

 

Create a JHipster application

This template utilizes JHipster version 2.6.0.

If you do not yet have JHipster installed, then please take a look at the Installation Documentation on the JHipster website.  When prompted to install JHipster from the command line with the npm install command please enter the following:

Note that if you have a newer version of JHipster, this will override it.

After the installation has completed, you can verify your JHipster version with the following command:

After you have installed JHipster on your system you can generate an application.

Create an empty directory for JHipster.

Navigate into the directory.

Generate your application.

While generating your JHipster application, select the following settings when prompted. The selected settings will allow for the highest level of integration between JHipster and this template.

Note that you will be prompted to make more selections than shown below, however those choices will not affect the correctness of the generated entities.

Do you want to use Java 8?
Yes (use Java 8)

Which *type* of authentication would you like to use?
HTTP Session Authentication

Which *type* of database would you like to use?
SQL (H2, MySQL, PostgreSQL)

Which *production* database would you like to use?
PostgreSQL

Which *development* database would you like to use?
H2 in-memory

Do you want to use Hibernate 2nd level cache?
No

Choose Maven as the build tool.

 

Generate entities and changelogs with JHipster

At this stage we can create the entities that will be utilized in our application. In my case, I will use JHipster to create the Book entity that will be utilized in The Developer’s Bookshelf.

JHipster is capable of creating entities that have complex relationships with other entities. Note that when dealing with one-to-many relationships, there is a specific order you must follow when creating your entities. Look through the JHipster documentation for more details.

The Book entity is created by navigating into the JHipster application directory and running the following command:

The Book entity will have the following properties:

  • a “name”, of type “String”
  • a “publisher”, of type “String”
  • a “dateOfPublication”, of type DateTime
  • a “description”, of type “String”
  • a “photo”, of type “String”

When prompted, you can choose whether or not you would like pagination for your entity. For The Developer’s Bookshelf, I will select ‘No’.

JHipster will now generate a number of useful classes and files for our new entity.

 

Transfer entities and changelogs to the template

The Book entity has been created in the JHipster application. We can now transfer the Book entity’s domain class, its repository, and also the Liquibase changelog into our template application.

  1. Copy the Book class from the ‘domain’ package in JHipster to the ‘domain’ package in the template application.
  2. Copy the BookRepository class from the ‘repository’ package in JHipster to the ‘repository’ package in the template application.
  3. Copy the “201x…_added_entity_Book.xml” file from the src/main/resources/config/liquibase/changelog folder in JHipster to the folder of the same name in the template application.
  4. Copy the “master.xml” file from the src/main/resources/config/Liquibase folder in JHipster to the folder of the same name in the template application and overwrite the original.

 

Customize entities and changelogs

Customize the generated entities and changelogs to suit your needs.

If you are interested in having Liquibase populate your database with initial data, then please take a look at the Liquibase Extras heading in the Spring Boot + Thymeleaf + Heroku Template web page that describes the features of the template.

 

Modify the local database

An embedded H2 database is the default local development database for this template so that it can be run from the command line without any modifications.

I would recommend using a PostgreSQL database for local development since Heroku is utilizing a PostgreSQL database in Production. This will enable you to catch database errors locally before they are deployed to Heroku where they are more complicated to troubleshoot.

Here are the steps for converting the template so that it is utilizing a local PostgreSQL database in development.

  1. Install PostgreSQL on your system and make sure the PostgreSQL service is running.
  2. Create a new database called sample, or any other database name of your choosing.
  3. Set the owner of the new sample database to postgres.
  4. Navigate to the following project directory: src/main/resources/config
  5. Rename “application-dev.yml” to “application-dev (H2).yml”
  6. Rename “application-dev (PostgreSQL).yml” to “application-dev.yml”.
  7. Open up the new “application-dev.yml” file and modify the password field so that it holds your postgres user password.
  8. $ mvn clean install
  9. $ mvn spring-boot:run
  10. Open up the sample database and verify that the following two Liquibase tables have been generated: ‘databasechangelog’ & ‘databasechangeloglock’.

 

Develop the application

At this point, you can develop the application as you would any other Spring + Thymeleaf application. Develop your services, controllers, unit tests, integration tests, and anything else required for your application.

As an example, The Developer’s Bookshelf has the following BookService class.

 

The Developer’s Bookshelf has the following BookController class.

 

Deploy application

The application can be tested locally as described earlier by doing the following:

Navigate to the project on the command line.

Navigate to http://localhost:8080.

In order to update your Heroku application, first of all make sure that your Git repository is fully up to date. Afterwards, you can push your changes to Heroku as follows:

Wait for Heroku to load your application.

Look at your application logs to see what is happening behind the scenes

If your application deploys without timing out then open it as follows

You should now see your project online being hosted on your Heroku account.

 

Conclusion

And that concludes this tutorial on how to utilize the Spring Boot + Thymeleaf + Heroku Template in order to rapidly develop Spring + Thymeleaf applications. If you have any questions about the template or have any suggestions, please feel free to contact me.