rkpin2online/Spring-Boot-Application-Template

Spring Boot Web App, Flyway, MySQL, H2DB, Bootstrap, Thymeleaf, JWT, Swagger, API Rate Limiting, Docker, RBAC, i18n

Spring Boot Application Template/Starter-Project

The only thing better than a Maven archetype is a repo you can fork with everything already setup to speed up the creation of new Spring Boot based Web applications, just fork-and-code.

This repository contains a recipe/scaffolding for bootstrapping a Monolithic Web Application with the features & Technology stack listed below. Delete the sample code (or keep it.) and add your own, you’re good to go.

Explore the docs »

Report Bug · Request Feature

Service	Badge	Badge	Badge	Badge	Badge
GitHub
GitHub
Build/Quality
Others
Tech
Docker
Security
lgtm

Important Note: This project's new milestone is to release version 1, so stay tuned.

Table of Contents

• Application screenshots
• Technology stack & other Open-source libraries
  • Data
  • Client - Frontend/UI
  • Server - Backend
  • Libraries and Plugins
  • Others
  • External Tools & Services
• Features and To-Do
• Getting Started
  • Prerequisites
  • EER Diagram
• Installing
  • Running the application with IDE
  • Running the application with Maven
  • Running the application with Executable JAR
    • Accessing Data in H2 Database
      • H2 Console
  • Running the application via docker container
• Deployment
  • Deploying to Heroku
• Code Coverage
  • Cobertura
• Testing API
  • Testing with Postman Runner
  • Testing with Maven
  • Basic Load Testing
• Security
• Explore Rest APIs
• Documentation
• Internationalization (i18n)
• Files and Directories Structure
• Reporting Issues/Suggest Improvements
• The End
• Contributing
• License
• FOSSA third-party code, license compliance and vulnerabilities
• Contact

Application screenshots

More Screenshots

Technology stack & other Open-source libraries

Data

• Flyway - Version control for database
• MySQL - Open-Source Relational Database Management System
• H2 Database Engine - Java SQL database. Embedded and server modes; in-memory databases

Client - Frontend/UI

• Bootstrap - Bootstrap is a free and open-source CSS framework directed at responsive, mobile-first front-end web development.
• Bootstrap Table - An extended table to the integration with some of the most widely used CSS frameworks.
• Thymeleaf - Modern server-side Java template engine for both web and standalone environments.

Server - Backend

• JDK - Java™ Platform, Standard Edition Development Kit
• Spring Boot - Framework to ease the bootstrapping and development of new Spring Applications
• Maven - Dependency Management
• JSON Web Token - Encode or Decode JWTs

Libraries and Plugins

• Bootstrap ToC - Table of Contents plugin for Bootstrap
• Thymeleaf With Dialect - A dialect for Thymeleaf that allows you to use attributes with a "with" prefix to avoid having long "th:with"-expressions.
• Thymeleaf Layout Dialect - A dialect for Thymeleaf that lets you build layouts and reusable templates in order to improve code reuse.
• Lombok - Never write another getter or equals method again, with one annotation your class has a fully featured builder, Automate your logging variables, and much more.
• Swagger - Open-Source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services.
• Bucket4j - Java rate limiting library based on token/leaky-bucket algorithm.

Others

• git - Free and Open-Source distributed version control system
• Prometheus - Monitoring system and time series database
• Docker - A set of platform as a service products that use OS-level virtualization to deliver software in packages called containers.

External Tools & Services

• Mailtrap - Safe Email Testing for Staging & Development.
• Postman - API Development Environment (Testing Docmentation)
• Postman Echo - A service that can be used to test your REST clients and make sample API calls. It provides endpoints for GET, POST, PUT, various auth mechanisms and other utility endpoints.
• Travis CI - A hosted continuous integration service used to build and test software projects hosted at GitHub and Bitbucket.
• Codecov - A hosted tool that is used to measure the test coverage of your codebase.
• Dependabot - Automated dependency updates.
• FOSSA - Scalable, end-to-end management for third-party code, license compliance and vulnerabilities.
• sonarcloud - Cloud-based code analysis service designed to detect code quality issues continuously ensuring the maintainability, reliability and security of code.
• gitignore.io - Create useful .gitignore files for your project.

Features and To-Do

• Logger (Console, File)
• Content Negotiation
• Dark Mode
• Spring Security RBAC, Session Timeout
• API Rate Limiting
• JPA Auditing via AuditorAware Interface
• Spring Profiles (dev, production, qa, staging, test)
• Docker
• Caching
• HATEOS (Hypermedia as the Engine of Application State)
• Software documentation - Swagger, Javadoc, Postman Collection
• HTTPS with (self-signed certificate)
• JSON Web Token based authentication
• Quartz Scheduler
• Multiple Databases
• jOOQ
• Replace Docker with jib
• Unit Tests, Integration Tests
• Shut down app on button click via actuator url
• Spring Boot Admin
• NoSQL (MongoDB)
• Multitenancy
• Micrometer
• Grafna
• Spring Retry

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

• To activate the accounts of registered users, an email with activation link is sent to the email provided during the user signup stage. An SMTP is required for the same.

  Mailtrap or any other service like Gmail, etc., can be used to create an SMTP.

  update the springMailHost, springMailPort, springMailProtocol, springMailUsername and springMailPassword details in the application_settings section of /resources/data/mysql/migrations/V0_0_4__populate_data.sql

• You need to have MySQL installed on your machine to run the application in dev profile. Using the MySQL Workbench or on any other MySQL client/console, create a database/schema named sbat.

-- create schema
CREATE SCHEMA sbat;

-- use schema
USE sbat;

-- Create user 
create user 'sbat'@'localhost' identified by 'sbat';

-- Grant privileges to user
grant all privileges on *.* to 'sbat'@'localhost' with grant option;

After creating the database/schema, you need to add your MySQL username and password in the application-dev.properties file on src/main/resource. The lines that must be modified are as follows:

spring.datasource.url=jdbc:mysql://localhost:3306/sbat?useSSL=false&allowPublicKeyRetrieval=true
spring.datasource.username=sbat
spring.datasource.password=sbat

• A Java Keystore File is required to generate JSON Web Token.

keytool -genkey -alias redditclone -keyalg RSA -keystore redditclone.jks -keysize 2048

EER Diagram

• Refer to ARCHITECTURE.md for details.

Installing

• Default active profile is test. When the application is running, Flyway will create the necessary tables and system data along with sample data. In the test profile, the application uses H2 database (data in memory).

• URL to access application UI: http://localhost:8080/sbat/index or https://192.168.99.102:8080/sbat/index if SSL is enabled.

Running the application with IDE

There are several ways to run a Spring Boot application on your local machine. One way is to execute the main method in the com.arc.sbtest.SBtemplateApplication class from your IDE.

• Download the zip or clone the Git repository.
• Unzip the zip file (if you downloaded one)
• Open Command Prompt and Change directory (cd) to folder containing pom.xml
• Open Eclipse
  • File -> Import -> Existing Maven Project -> Navigate to the folder where you unzipped the zip
  • Select the project
• Choose the Spring Boot Application file (search for @SpringBootApplication)
• Right Click on the file and Run as Java Application

Running the application with Maven

Alternatively you can use the Spring Boot Maven plugin like so:

$ git clone https://github.com/Spring-Boot-Framework/Spring-Boot-Application-Template.git
$ cd Spring-Boot-Application-Template
$ mvn spring-boot:run

Running the application with Executable JAR

The code can also be built into a jar and then executed/run. Once the jar is built, run the jar by double clicking on it or by using the command

$ git clone https://github.com/Spring-Boot-Framework/Spring-Boot-Application-Template.git
$ cd Spring-Boot-Application-Template
$ mvn package -DskipTests
$ java -jar target/SBtemplate-0.0.1-SNAPSHOT.jar --spring.profiles.active=test

To shutdown the jar, follow the below mentioned steps on a Windows machine.

• In command prompt execute the jcmd command to print a list of all running Java processes
• Taskkill /PID PROCESS_ID_OF_RUNNING_APP /F execute this command by replacing the PROCESS_ID_OF_RUNNING_APP with the actual process id of the running jar found out from executing the previous command

Accessing Data in H2 Database

H2 Console

URL to access H2 console: http://localhost:8080/h2-console/login.jsp or https://192.168.99.102:8080/h2-console/login.jsp if SSL is enabled.

Fill the login form as follows and click on Connect:

• Saved Settings: Generic H2 (Embedded)
• Setting Name: Generic H2 (Embedded)
• Driver class: org.h2.Driver
• JDBC URL: jdbc:h2:mem:sbat;MODE=MySQL
• User Name: sa
• Password:

Running the application via docker container

• Refer to DOCKER.md for details.

Deployment

Deploying to Heroku

• Download and install the Heroku CLI
• log in to your Heroku account heroku login
• set git remote heroku to the heroku app url, example heroku git:remote -a spring-boot-app-template
• Add and Commit any pending changes to git
• push the code to heroku to deploy the app, example git push heroku master

Code Coverage

Cobertura

Generating code coverage reports

$ mvn cobertura:cobertura

This will create a detailed HTML style report showing code coverage statistics gathered via code instrumentation.

Spring-Boot-Application-Template\target\site\cobertura

Testing API

Testing with Postman Runner

Import the Spring Boot Application Template API.postman_test_run file into postman and run the API tests.

Testing with Maven

• Run only unit tests:

$ mvn clean test

Basic Load Testing

Basic load testing for retrieving a person for a given id can be performed with the ApacheBench by executing the following command:

ab -n 10000 -c 100 -k http://localhost:8080/api/v1/person/1

• -n 10000 is the number of requests to make
• -c 100 is the number of concurrent requests to make at a time
• -k sends the KeepAlive header, which asks the web server to not shut down the connection after each request is done, but to instead keep reusing it

Result:

Benchmarking localhost (be patient)
Completed 1000 requests
Completed 2000 requests
Completed 3000 requests
Completed 4000 requests
Completed 5000 requests
Completed 6000 requests
Completed 7000 requests
Completed 8000 requests
Completed 9000 requests
Completed 10000 requests
Finished 10000 requests


Server Software:
Server Hostname:        localhost
Server Port:            8080

Document Path:          /api/v1/person/1
Document Length:        132 bytes

Concurrency Level:      100
Time taken for tests:   9.213 seconds
Complete requests:      10000
Failed requests:        0
Non-2xx responses:      10000
Keep-Alive requests:    0
Total transferred:      5330000 bytes
HTML transferred:       1320000 bytes
Requests per second:    1085.38 [#/sec] (mean)
Time per request:       92.133 [ms] (mean)
Time per request:       0.921 [ms] (mean, across all concurrent requests)
Transfer rate:          564.95 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    1   1.1      1      49
Processing:    13   91  30.1     85     523
Waiting:        0   68  29.3     65     472
Total:         14   91  30.1     85     523

Percentage of the requests served within a certain time (ms)
  50%     85
  66%     95
  75%    101
  80%    105
  90%    119
  95%    136
  98%    176
  99%    223
 100%    523 (longest request)

Security

• Refer to APP_SECURITY_AND_API.md for details.

Explore Rest APIs

• Refer to APP_SECURITY_AND_API.md for details.

Documentation

• Postman Collection - online, with code auto-generated snippets in cURL, jQuery, Ruby,Python Requests, Node, PHP and Go programming languages
• Postman Collection for offline testing is available in the postman folder.
• Swagger - http://localhost:8080/swagger-ui.html- Documentation & Testing
• Swagger - http://localhost:8080/v2/api-docs?group=Spring%20Boot%20Application%20Template- Documentation & Testing
• Find Java Doc in javadoc folder
• Java Doc is generated in Spring-Boot-Application-Template\target\site\apidocs folder using the Maven command

`mvn javadoc:javadoc`                   //Generate JavaDoc

Internationalization (i18n)

This app can be adapted to various languages and regions without engineering changes. Textual elements, such as status messages and the GUI component labels, are not hardcoded in the program. Instead they are stored outside the source code and retrieved dynamically.

Refer io.github.anantharajuc.sbat.backend.config.I18Nconfiguration. The text elements are stored in \src\main\resources\i18n folder.

Files and Directories Structure

• Refer to ARCHITECTURE.md for details.

Reporting Issues/Suggest Improvements

This Project uses GitHub's integrated issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations below:

• Before you log a bug, please search the issue tracker to see if someone has already reported the problem.
• If the issue doesn't already exist, create a new issue
• Please provide as much information as possible with the issue report.
• If you need to paste code, or include a stack trace use Markdown +++```+++ escapes before and after your text.

The End

In the end, I hope you enjoyed the application and find it useful, as I did when I was developing it to create a Spring Boot web application template with good/convenient practices for rapid prototyping.

If you would like to enhance, please:

• Open PRs,

• Give feedback,

• Add new suggestions, and

• Finally, give it a 🌟.

• Happy Coding ...* 🙂

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

Kindly refer to CONTRIBUTING.md for important Pull Request Process details

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

FOSSA third-party code, license compliance and vulnerabilities

Contact

Anantha Raju C - @anantharajuc - arcswdev@gmail.com

Project Link: https://github.com/Spring-Boot-Framework/Spring-Boot-Application-Template