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).
.gitlab-ci.yml
.github
directorygroup
namename
spring.application.name
And now go do the real work :-)
This project requires Java 21 (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.
The credentials to login are: user
/password
The Project Lombok Eclipse integration must be setup. See the Eclipse instructions on Project Lombok's site.
Cypress is a frontend e2e / integration testing framework. You will find all the Cypress tests in the frontend/cypress
directory.
There are a few ways to run cypress tests locally:
./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../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.
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 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.
There are a few ways to run cypress tests locally:
./gradlew bootTestRun
,then, from within the frontend
directory, run ./npx lhci autorun --collect.startServerCommand=""
frontend
directory, run ./npm run lhci autorun
This command will start the application for you../gradle test
. One of the tests run is LighthouseTest
which will run the Lighthouse tests. This approach is used by .gitlab-ci.yml
when running continuous integration.The configuration file at frontend/lighthouserc.yml
can be modified to suit your application's needs. In this file, Lighthouse is configured to run a Puppeteer script at frontend/puppeteer-script.js
that will log in to site allowing Lighthouse to test the authenticated experience.
The GitLab CI pipeline is implemented in .gitlab-ci.yml
. It features these stages each containing jobs:
lint
stage runs code linters
codespell
jobs checks spelling in the source codebuild
stage runs the build, producing the output artifact (a jar)
build and test
job runs the gradle build task. That task compiles the code, assembles the jar, and runs the tests. Frontend Cypress tests are run as part of this job as well, for details see [#the-combined-build-and-test-job](the combined build and test
job) section.test
stage runs tests
convert jacaco to cobertura coverage
job converts the jacoco formatted test report produced by Gradle in the build and test
job to cobertura format which is used by GitLab. This job exists as a workaround for GitLab issue: Support JaCoCo coverage reports for coverage visualization
In GitLab CI, stages run in the order they're listed in the stages
block. If any stage in a job fails (unless that job is explicitly specified as being allow to fail), then no later stages will run. For example, if there is a spelling error then the codepsell
jobs fails and therefore no jobs in the build
stage will run.
The
services
keyword defines a Docker image that runs during a job linked to the Docker image that the image keyword defines. This allows you to access the service image during build time. --- GitLab CI services
An common example of how to use services is to define a database service then have the job use the service to run tests.
This project takes a slightly different approach and only uses one service, Docker in Docker (aka dind). Docker in Docker allow a job to start Docker containers itself instead of having to define them as services
in .gitlab-ci.yml
. By using Testcontainers, the tests use Docker in Docker to start a database for tests to run against. This project also uses testcontainers in a Cypress container for those tests, see the Cypress Tests section for details. The advantage of this approach is that the tests are not coupled to GitLab CI; the tests can run on any system that supports Docker in Docker. This means that developers can run the tests on their own systems without need to commit, push, and wait for results from GitLab CI - and because the same Docker images are used, developers can be confident that when a test passes on their system, it will also pass when run in GitLab CI.
build and test
jobSome pipelines have separate build
and test
jobs but this pipeline only has one job, build and test
. The reasoning behind the combined build and test
is:
build and test
was split into build
and test
jobs, overall pipeline run time would actually be longer (it takes time to start new jobs, so less jobs means less time).build and test
job that runs ./gradlew build
is simpler than having 2 jobs, one build
that does ./gradlew build -x test
and a test
job that does ./gradlew test
.There are good reasons to have separate build
and test
jobs though. For example:
image
defined for its job, so it should have a separate job.