Spring Boot + Thymeleaf + Heroku Template

After an extensive search on GitHub, and the rest of the Internet in general, I was unable to find a project that would allow me to rapidly develop Spring applications with Thymeleaf that were fully deployable to Heroku. Since I was unable to find what I was looking for, I decided to create it and then share it.

In the creation of this template, I wanted something lean that would run on one Heroku dyno so that I could rapidly develop prototypes without too many bells and whistles. I also wanted something that integrated properly with JHipster so that I could quickly and easily generate entities and database changelogs. JHipster is an incredible project that is leading the way in the rapid development of Spring applications. The project is a Yeoman generator used to create Spring + AngularJS projects, with full hot reload of Java and JavaScript code.


The Spring Boot + Thymeleaf + Heroku Template is available on GitHub. There is a detailed description of how to get up and running quickly on the project’s main page.

Live Demo

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 Spring Boot + Thymeleaf + Heroku Template running on Heroku.

Suggested Usage

As described on GitHub, this project has been designed so that JHipster version 2.6.0 can be utilized to rapidly generate entities and Liquibase database changelogs that can then be transferred into this template. Entity classes can be transferred from JHipster’s domain package. Liquibase changelogs can be transferred from JHipster’s src/main/resources/config/liquibase folder.

Detailed Walkthrough

The rest of this blog post will describe the features of the template. For a detailed walkthrough of how to utilize the template, please see The Developer’s Bookshelf with Heroku where I show the steps involved in rapidly building a demo application.


Technology Stack

  • Spring Boot, no-xml Spring MVC 4 web application for Servlet 3.0 environment
  • Thymeleaf templates with added Joda Time & Spring Security Dialects
  • Heroku fully cloud deployable
  • JPA 2.0 (Spring Data JPA/Hibernate)
  • Database (Liquibase/PostgreSQL/H2 embedded/HikariCP)
  • Testing (JUnit/Mockito/MockMVC/AssertJ/Hamcrest)
  • Java 8, Spring Security 3.2, Maven 3, SLF4J, Logback, Bootstrap 3.3.4, jQuery 1.11.2, i18n, etc


No-XML Configuration

All of the Spring configuration for the application can be found in the com.chrisbaileydeveloper.myapp.config package shown in the picture below. Because of Spring Boot, there is minimal configuration as it auto-configures much of the application on its own.

Spring Configuration Classes

Constants.java – Holds two String constants that are used to set the profile for the application to either development or production.

DatabaseConfiguration.java – This class configures the development profile’s DataSource as well as Liquibase.

HerokuDatabaseConfiguration.java – The production profile’s DataSource is configured in this class. This is the DataSource that will be utilized when deploying to Heroku.

LocaleConfiguration.java – The default locale can be set in this class as well as the variable name that will be utilized in the URL to signify the locale (the default is set to lang). Two message sources on the classpath are enabled by default, namely /i18n/messages and /i18n/application .

The class also configures the JodaTimeDialect and the SpringSecurityDialect that will be discussed in more detail later in this post. Note that Spring Boot, in the ThymeleafAutoConfiguration class, will automatically add any Beans that implement the IDialect interface.

SecurityConfig.java – Two in-memory users are created in the configureGlobal method. The configure method allows you to set permissions for the URLs of your application as well as setup login/logout pages.


Thymeleaf Templates with Added Dialects

By default, Spring Boot expects to find Thymeleaf templates in the templates directory on the classpath.
Thymeleaf templates

For example, returning the string “home/index” in a Controller class will resolve to the /templates/home/index.html Thymeleaf template.

Two dialects have been added to this project which simplify working with Joda Time and Spring Security within Thymeleaf templates.

JodaTimeDialect – The JodaTime Thymeleaf Dialect allows you to show JodaTime values in Thymeleaf templates with minimal effort. Documentation for how to use the dialect is shown in the link given.

As an example, the following Thymeleaf snippet will display your JodaTime date variable in the mediumDate format.

SpringSecurityDialect – The Spring Security Dialect has been added to this template, which enables the Spring Security 3 integration module for Thymeleaf. As shown on the Thymeleaf + Spring Security Integration Basics page, this dialect provides a direct equivalent to the Spring security taglib.

For example, the following <div> will only be shown to administrators.

A number of examples can be seen in the template project within the index.html , footer.html , and header.html files.


Heroku Fully Cloud Deployable

The steps required in order to deploy the application to Heroku are documented in the project’s GitHub main page. Additionally, Heroku utilizes a couple of configuration files that are of interest.

Procfile – This file holds the command that Heroku will execute when it attempts to run your application.

system.properties – This file holds the version of Java you are using in your application.


Database Configuration

Although the template comes packaged with an H2 embedded database for the development environment, I would recommend moving over to a PostgreSQL database. The steps involved are documented in the project’s GitHub main page under the Local Database Selection heading. This will enable you to catch database errors locally before they are deployed to Heroku where they are more complicated to troubleshoot.


Liquibase Extras

Liquibase can populate your database from a CSV file which I find to be quite useful.

Firstly, I will generate a Book entity with JHipster that has the following properties:

After generating my Book entity I will transfer over the domain class as well as the changelogs. The Liquibase directory will now take the following form:

Liquibase Configuration

If you open the ..._added_entity_Book.xml file you will notice that you have a <changeSet> that will create a table called T_BOOK that will hold your Book entities.

In order to populate the T_BOOK table, I will add the following code before the </changeSet> .

I will now create a CSV file called books.csv located in the liquibase folder that will contain the following data.

Liquibase will now populate my database with the Book entities given in the CSV file.


Spring Testing

The src/test/java folder holds the HomeControllerTest.java and the SigninControllerTest.java classes. They are simple classes, but they contain the basic structure required for much more complicated Spring testing.

Note that if you have populated your database with Liquibase as discussed earlier, then you can utilize those database objects while testing your Service classes.

For example, the following unit test will verify that the findBook method in the BookService class retrieves the expected Book from the database.


Static Content (CSS, JS, images)

Spring Boot will automatically add static web resources located within any of the following directories:

  • /META-INF/resources/
  • /resources/
  • /static/
  • /public/

Currently, all static files are being served from the /static/ folder in the following directory structure:

Static files

With this directory structure, Thymeleaf can access CSS/JS files as follows:


Special Thanks

A big thank you to Julien Dubois and the JHipster project for leading the way in the rapid development of Spring applications, as well as for part of the foundation for this template. JHipster is a Yeoman generator used to create Spring + AngularJS projects, with full hot reload of Java and JavaScript code.

Also, thank you to Rafal Borowiec’s for his impressive spring-mvc-quickstart-archetype project.


Questions or Clarification

If you have any questions or require any clarification on any parts of the Spring Boot + Thymeleaf + Heroku template please feel free to contact me.