spring-skeleton

Spring Boot skeleton to kick-start your new application.

Table of Contents

• 1. What is included?
• 2. Usage
  • 2.1. Set project group and artifact name
  • 2.2. Build and run
• 3. OpenAPI 3.0 documentation
• 4. Swagger UI
• 5. Observability
• 6. Postgres CLI
• 7. Redis CLI
• 8. Testing
• 9. Code formatting
• 10. Git hooks
• 11. Registration and login flow
• 12. License

1. What is included?

• Spring Boot

• Postgres database with Spring Data JPA

• Preconfigured Spring Security, with session information stored in Redis

• Lombok

• OpenAPI 3.0 documentation and Swagger UI

• Spring Boot Actuator

• Spring Boot Devtools

• Spotless with Prettier code formatter

• Observability with OpenTelemetry + Loki + Prometheus + Tempo + Grafana

2. Usage

2.1. Set project group and artifact name

Use init.sh script to initialize a new project with the given group and artifact name:

./init.sh group artifact

2.2. Build and run

Run external service dependencies in Docker:

docker compose up -d

Build and run the app locally:

./gradlew bootRun

3. OpenAPI 3.0 documentation

OpenAPI documentation is available on the following link: http://localhost:8080/v3/api-docs

💡	jq utility can be installed in order to interact with the JSON output directly from the CLI. For example, the following command will list all available endpoints: curl http://localhost:8080/v3/api-docs | jq '.paths|keys'

4. Swagger UI

Swagger UI is available to visualize and interact with the API’s resources. It is available on the following link: http://localhost:8080/swagger-ui.html

5. Observability

Logs, metrics and tracing are available in Grafana on the following link: http://localhost:3000

6. Postgres CLI

Use the following command to connect to the Postgres instance:

docker-compose exec database psql -U postgres

7. Redis CLI

Use the following command to connect to the Redis instance:

docker-compose exec session redis-cli

8. Testing

To run all tests, use the following command:

./gradlew test

9. Code formatting

To run code formatter, use the following command:

./gradlew spotlessApply

10. Git hooks

Pre-commit hook is available in .githooks directory. It is configured to run ./gradlew spotlessApply.

In order to use it, run the following command:

git config core.hooksPath .githooks

11. Registration and login flow

The following is an example of registration and login flow using httpie:

1. Get a CSRF token:

   http --session=admin --offline --quiet ':8080' \
       "X-XSRF-TOKEN: $(http --session=admin ':8080/csrf' | jq --raw-output .token)"

2. Register:

   http --session=admin ':8080/users' email=admin@example.com password=Password1

3. Login:

   http --session=admin ':8080/login' email=admin@example.com password=Password1

4. Fetch user info

   http --session=admin ':8080/users/self'

5. Logout

   http --session=admin POST ':8080/logout'

12. License

Copyright (C) 2021-2023 Bojan Stipic

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.