Installing the Archetype

We’ll start by cloning the archetype repository so we can install it. If the archetype will be published in Maven Central at some point, this step will be different but for now we will do it like this. Make sure Eclipse is open and ready.

• Clone https://github.com/diging/spring-thymeleaf-archetype.git using your favorite Git client.

• Go to Eclipse.

• Right-click into the Project Explorer or if that doesn’t work choose “File > Import…”. Or if you see a list of options in the Project Explorer (if you have an empty workspace, you might see this) click “Import projects…”

• In the import wizard, choose “Projects from Git” from the list and click “Next.”

  Open

  

• Choose “Existing local repository” and click “Next.”

• Add the Git repository you cloned in the first step, select spring-thymeleaf-archetype from the list that should appear after you added the repository, and click "Next."

• Make sure “Import existing Eclipse project” is selected, open the “Working Tree” folder and select archetype. Click "Next."

  Open

  

• Make sure archetype is selected. Click “Finish.”

• If archetype is not listed, go back to previous page and make sure “Import as general project“ is selected. Click “Next.“ Make sure archetype is selected. Click “Finish.” Then, right-click the project in the File Explorer and select “Configure > Convert to Maven Project.“

• The project should now show up in your Project Explorer with a little M decorator indicating that it’s a Maven project.

• Right-click on the project and choose “Run as > Maven install.”

• In the console, you should see a bunch of output ending with something like this

  [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 24.405 s [INFO] Finished at: 2023-01-18T12:39:37-05:00 [INFO] ------------------------------------------------------------------------

The Maven archetype (Maven template) is now installed in your local Maven repository.

Creating a new project

Now we can create a project from the archetype.

• Right-click in the Project Explorer and select “New > Project…”

• In the New Project wizard, select open the Maven folder and select “Maven Project.” Click “Next.”

• On the “New Maven project” page, make sure “Create a simple project (skip archetype selection)” is not selected. Click “Next.”

• On the “Select an archetype” page, choose “Default Local” from the “Catalog” dropdown. The archetype we just installed, should show up.

• Select the archetype (spring-thymeleaf-webapp) and click "Next."

• Enter a group id and artifact id. The values do not matter too much, but the group and artifact ids will be used as base package name by default. Click “Finish.”

Maven is now creating your project. This might take a while. In the console you can probably see Maven’s log output. If the console stops in between asking you to confirm the properties configuration, just hit enter.

Your project structure of the newly created project, should look something like this:

If you are using Java 11, you will probably see the above errors on the project. To fix those:

• open pom.xml

• find the plugin with the artifact id maven-war-plugin

• Upgrade the version to 3.3.1

  <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.1</version> <configuration> <webResources> <resource> <filtering>true</filtering> <directory>src/main/webapp</directory> <includes> <include>**/*</include> </includes> <excludes> <exclude>**/*.woff</exclude> <exclude>**/*.ttf</exclude> <exclude>**/*.woff2</exclude> </excludes> </resource> </webResources> </configuration> </plugin>

Next, we need to fix the compilation issues in SimpleUsersConfig.

• Open SimpleUsersConfig.java

• Remove lines 4 and 5.

  import my.project.simpleusers.core.config.SimpleUsers; import my.project.simpleusers.core.config.SimpleUsersConfiguration;

• Organize imports by either right-clicking in the editor and selecting “Source > Organize Imports” or by using the keyboard shortcut (cmd-shift-o on Mac).

• Save the file. The compilation errors should be gone now.

Running the project

To run the project:

• Right-click it, and select “Run as > Run on Server.”

• In the dialog, open the “Apache” folder and select “Tomcat v9.0 Server.”

• Click “Next,” select the Tomcat installation directory (make sure you have downloaded Tomcat 9.0).

• Click “Finish.”

The server should be starting but there should be exceptions in the log. You should find an exception in the log that says:

You see this exception because we have not yet setup a database to which the application can connect. Currently, the application tries to connect to a database jdbc-url-to-db, which does not exist. To fix this, create a new MySQL database in your favorite client and a user that has write access to that database (the user needs to be able to create tables, change them, etc).

Fix for MySQL 8

If you are using MySQL 8, you will need to adjust the dialect Hibernate uses to create database tables. To do this, do the following:

• Open PersistenceConfig.java

• In line 73, change the Hibernate dialect to org.hibernate.dialect.MySQL8Dialect

   

If you do not adjust the dialect, you will see “key too long” exception when starting the server.

Provide database config

Then provide the details of the database in the POM file.

• Open pom.xml.

• Find the part with the database properties.

• Replace jdbc-url-to-db with the url to the database (something like jdbc:mysql://localhost:3306/databaseName)

• Replace db-user with the db user’s username.

• Replace db-password with the password of the db user.

• Now right-click the project and select “Maven > Update Project…”

• Make sure thymeleaf is selected and click “Ok.”

• Restart the server.

The server should now start without errors and you should get the main app home page at http://localhost:8080/thymeleaf/ (or http://localhost:8080/spring-thymeleaf-artifact/ if you have committed the code to a Git repository).

A bug finding challenge

You should now be able to run the app and see something like this:

But try to login. Username is admin and password is admin. You will see an error message. Try to fix it. If you need some help, the next page will give you some tips. But try it by yourself at first. Being able to resolve bugs is an important skill for any software developer.