Jumpstart for Spring Boot with Postgres and React

What is this project?

This repository contains be a clonable application intended to jumpstart new projects. Many Spring Boot project start off in the same way with similar basic requirements, such as a frontend, some security, a database, and testing. Projects also always benefit from the application of the best practices. Rather than reinvent the wheel each time a new project kicks off, this jumpstart allows new efforts to get a solid foundation easily allowing the team to get to the real work quickly.

The demonstrated application itself is a simple "Hello World" application. There is a Spring Boot based backend that connects to a Postgres database. The backend serves the frontend which is a React application. The application is horizontally scalable and fault tolerant (through Spring Session JDBC).

Included Technologies

Backend
- Java 25
- Spring Boot
- Project Lombok
- Gradle
- Testcontainers (not used in production)
- Spring Security (demonstrating with a simple, single user configuration)
- JUnit 5
- MockMvc
- Liquibase
Frontend
- NPM
- ReactJS
- TypeScript
- Vite
- React Testing Library
- Cypress
Services
- PostgreSQL
Miscellaneous
- GitLab CI Not using GitLab? Delete .gitlab-ci.yml
- GitHub Actions Not using GitHub? Delete the .github directory
- Renovate configuration included to keep dependencies up to date: renovate.json. See The How and Why Automating Dependency Updates.
Various code quality tools, linters, and performance testers, including (but not limited to):

Customizing to Jumpstart a New Project

In settings.gradle, change the project name
In build.gradle, change the group name
In frontend/package.json, change the name
In src/main/resources/application.yml, change spring.application.name
Change class names in src/main/java and src/test/java. IDE refactor is an easy method to do this.
Change this README.md
Change LICENSE. This work is distributed under CC0 1.0 Universal (CC0 1.0) Public Domain Dedication so you may use it however you want. But, that's probably not what you want for any new project you make with it.

And now go do the real work :-)

Developer Setup

This project requires Java 25 (or later). Import this Gradle project using your IDE of choice. Or, if you don't want to use an IDE, you can run the project from the command line: ./gradlew bootTestRun The site will be accessible at https://localhost:8443

Installing node and npm is not necessary. Gradle installs and manages node and npm; to use the gradle provided versions, run ./node and ./npm from the frontend directory.

By default, this project is set up to use Testcontainers to run all required services. Testcontainers requires docker. Test containers will attempt to start a privileged container for Ryuk; if you cannot start privileged containers, disable that functionality by setting the environment variable TESTCONTAINERS_RYUK_DISABLED=true

To use a postgresql database other than the one provided by testcontainers, set the SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, and SPRING_DATASOURCE_PASSWORD environment variables appropriately. For example, this command will connect to a local postgres database: SPRING_DATASOURCE_URL="jdbc:postgresql://localhost:5432/jumpstart" SPRING_DATASOURCE_USERNAME="someuser" SPRING_DATASOURCE_PASSWORD="somepassword" ./gradlew bootRun

If a frontend file is changed using an IDE (ex, IntelliJ or Eclipse), the change will automatically be applied in the running application using LiveReload. To have the change applied in the browser without having to refresh the page, install the appropriate LiveReload extension for your browser. Chrome Firefox Therefore, npm start isn't necessary - but it can still be used by running ./npm start from the frontend directory.

Local Site Credentials

The credentials to login are: user/password

Eclipse

The Project Lombok Eclipse integration must be setup. See the Eclipse instructions on Project Lombok's site.

Intellij

Import this directory as a gradle project
Install and enable IntelliJ plugins
1. Search all IntelliJ actions (Command + Shift + A) for "plugins"
2. Search "Spring" in installed plugins and enable all that appear
3. Search "PMDPlugin" and install from marketplace
4. Search "CheckStyle-IDEA" and install from marketplace
Go to Project Structure
1. Change to Java 21 (or later)
Go to Advanced Settings
1. Set "Allow auto-make to start even if deployed application is currently running" (See https://stackoverflow.com/a/68786501 for details)
Turn on Annotation Processor
1. Search all IntelliJ actions (Command + Shift + A) for "Annotation Processors" and click the result under "Preferences"
2. Check "Enable annotation processing" at the top of the window and apply changes
Restart IntelliJ
Run project
To verify project is running, navigate via browser to https://localhost:8443

Cypress Tests

Cypress is a frontend e2e / integration testing framework. You will find all the Cypress tests in the frontend/cypress directory.

Running the Cypress Tests

There are a few ways to run cypress tests locally:

Run the application, for example, by running ./gradlew bootTestRun,then, from within the frontend directory, either run:
- ./npm run cypress-open to open the Cypress GUI. This allows you to run individual tests in Chrome so you can watch them as they execute. This approach is great for debugging and visually verifying that your tests work.
- ./npm run cypress-run runs the entire test suite in a headless (Electron) browser all through the command line. This is an excellent option for just running the tests and seeing a pass/fail.
Run the application's tests with ./gradle test. One of the tests run is CypressTest which will run the Cypress tests. This approach is used by .gitlab-ci.yml when running continuous integration.

Regardless of approach, tests results (including screenshots and videos) are written to the build/reports/cypress/ directory.

Configuring Cypress

The configuration file at frontend/cypress.config.ts can be modified to suit your application's needs. Initially, it is set to run all Cypress tests from a base URL of https://localhost:8443. More information on configuration can be found in Cypress's configuration documentation.

Lighthouse Tests

Lighthouse is an open-source, automated tool for improving the quality of web pages. It is able to audit performance, accessibility, best practices, and more. You can run Lighthouse in Chrome DevTools, from the command line, or as a Node module. You give Lighthouse a URL to audit, it runs a series of audits against the page, and then it generates a report on how well the page did.

Running the Lighthouse Tests