Welcome to the Kavun project! It is a modern, opinionated, and production-ready starter for Spring Boot projects. It is designed to help developers get started with Spring Boot projects quickly and efficiently. The project includes a wide range of features and tools to help developers build robust and scalable applications. It is built using the latest technologies and best practices to ensure high performance, security, and maintainability.
It is a melon in Turkish. It is a sweet and juicy fruit that is popular in Turkey and other countries. It is known for its refreshing taste and high nutritional value. The name Kavun is chosen to represent the project's goal of providing a fresh, modern, and healthy start for developers working on Spring Boot projects.
- Spring Boot 3.4.2 - Inversion of Control Framework
- Bootstrap 5 - HTML, CSS, and JavaScript framework
- Thymeleaf - Modern server-side Java template engine
- Gradle - Dependency Management and Build Tool
- Lombok - Automatically plugs into your editor and build tools, spicing up your java.
- H2 - In-Memory Database for development
- Liquibase - Rapidly manage database schema changes.
- Spotless - Spotless is a general-purpose formatting plugin.
- Hibernate Envers - Detailed Auditing of CRUD operations.
- Spring Security
- Java Mail Sender
- Spring Configuration Processor
- Rest Repositories
- Spring Boot Actuator
- Spring Data JPA
- Validation
- Spring Boot DevTools
- Spring Data Jpa DataTables
- Test Containers
- ClamAV - Open Source Antivirus Engine
- Form and Rest Api Authentication based
- JWT Access and Refresh Tokens Support
- DataTables with Spring Data JPA
- OpenApi3 Swagger
- Form Validation
- Last Successful Login
- Bruteforce Attack Prevention using Failed Login Attempts
- Unit and Integration Tests
- API Login Controller
- Advanced CORS Configuration
- Fully Covered Equals, HashCode, ToString Testing
- Production Ready Folder Structure
- Authentication and Authorization with JWT
- Security Configuration Without WebSecurityConfigurerAdapter
- ClamAV Integration for File Scanning
- Dynamic Role and Permission Management
You can use any IDE of your choice. However, VSCode is recommended for this project. Before running the project, make sure the correct Java version is installed. You can check the Java version using the following command:
java -version# Move to your workspace
cd <your-workspace>
# Clone this project into your workspace
git clone <repository-url>
# Move to the project root directory
cd backend
# Open the project in your favorite IDE
code . # For Visual Studio Code
idea . # For IntelliJ IDEA# Start required services using Docker Compose
docker-compose up -d
# Run the application using Gradle (Windows / Linux / MacOS)
./gradlew bootRun
# Access the application on http://localhost:8080/
curl http://localhost:8080/- Alternatively, you can use the following commands for project setup:
# Run the application
./gradlew bootRun
# Run unit tests
./gradlew test
# Run integration tests
./gradlew integrationTest
# Run all tests
./gradlew testAll
# Rebuild the project
./gradlew clean build
# Run the project continuously (Hot Reload)
./gradlew bootRun --continuous --quiet
./gradlew bootRun -t
# Refresh Gradle Project (If you see "The import XXX cannot be resolved" error)
./gradlew --refresh-dependencies
# Run owasp dependency check
./gradlew dependencyCheckAnalyze --info
# When you add a new dependency, run the following command to refresh the dependencies
./gradlew build --refresh-dependencies
# Refresh dependencies
./gradlew clean build --refresh-dependencies
# Refresh dependencies without tests
./gradlew clean build --refresh-dependencies -x test -x integrationTest- Note: Before running the project, make sure to all the dependencies are installed and the project and connected to the databases.
The following environment variables can be customized as necessary:
# Application Configuration
admin.username=${ADMIN_USERNAME:admin}
admin.password=${ADMIN_PASSWORD:password}
admin.email=${ADMIN_EMAIL:admin@kavun.com}
access-token-expiration-in-minutes=${ACCESS_TOKEN_EXPIRATION_IN_MINUTES:60}
login.otp.enabled=${LOGIN_OTP_ENABLED:false}
login.captcha.enabled=${LOGIN_CAPTCHA_ENABLED:false}
app.test-otp-code=${APP_TEST_OTP_CODE:190303}
# AWS S3 Configuration
aws.region=${AWS_REGION:us-east-1}
aws.accessKeyId=${AWS_ACCESS_KEY_ID}
aws.secretAccessKey=${AWS_SECRET_ACCESS_KEY}
aws.s3BucketName=${AWS_S3_BUCKET_NAME:spring-boot-starter}
aws.servicePort=${AWS_SERVICE_PORT:8001}
aws.serviceEndpoint=${AWS_SERVICE_ENDPOINT:http://localhost:${aws.servicePort}}
# Mail Configuration
spring.mail.host=${MAIL_HOST:localhost}
spring.mail.port=${MAIL_PORT:465}
spring.mail.username=${MAIL_USERNAME:noreply@kavun.com}
spring.mail.password=${MAIL_PASSWORD:yourpassword}
spring.mail.protocol=smtp- The profiles defined in the application are development, docker, test, and production.
- By default, the application runs with the development profile.
- Access the application on http://localhost:8080/
- Access the H2 Database on http://localhost:8080/console
- Access the Swagger UI on http://localhost:8080/swagger-ui/index.html
- Access the Actuator Health on http://localhost:8080/actuator/health
- Access the Actuator Prometheus on http://localhost:8080/actuator/prometheus
- Access the Grafana Dashboard on http://localhost:3000/
- Access the Prometheus Dashboard on http://localhost:9090/
If you are not using DBeaver or any other database client, you can access the H2 database using the following steps:
# Open your web browser and go to http://localhost:8080/console
# The H2 database can be accessed using the following credentials:
- Saved Settings: Generic PostgreSQL
- Driver Class: Generic PostgreSQL
- JDBC URL: jdbc:postgresql://localhost:5432/kavun
- User Name: postgres
- Password: postgres
# Click on the Connect button to access the database.This configuration is used to connect to the H2 database. You can access .properties file to change the database configuration. The H2 database is only used for development and testing purposes. For production, the application uses the PostgreSQL database.
The application can be run on Docker using the following steps:
# Build the Docker image
docker build -t kavun-backend .
# Run the Docker container
docker-compose up -d
docker run -d -p 8080:8080 --name kavun-backend-container kavun-backend # If not using docker-compose
# Stop the Docker container
docker-compose down
docker stop kavun-backend-container && docker rm kavun-backend-container # If not using docker-compose
# Remove the Docker image
docker-compose down --rmi all
docker rmi kavun-backend # Be sure to stop and remove the container before removing the image
# Delete the Postgres data volume
docker volume rm <volume-name>The application uses Grafana for monitoring and visualization.
# Access Grafana Dashboard on http://localhost:3000/
# Default Grafana Credentials:
- Username: admin
- Password: adminThe project is structured in a layered architecture with the following layers:
.
├── config # Can hold project level configurations like pmd, checkstyle, etc.
├── docs # Holds project documentations. Markdown sections, etc.
│ └── images
├── libs # Holds special libraries used by the application.
│ └── newrelic
└── src
├── integrationTest # Integration test suites separated from unit tests.
│ ├── java
│ │ └── com
│ │ └── kavun
│ │ ├── backend
│ │ ├── task
│ │ └── web
│ └── resources
├── main
│ ├── java
│ │ └── com
│ │ └── kavun
│ │ ├── annotation # All custom annotations used in the application
│ │ ├── backend # Business Logic and Data Access implementation
│ │ ├── config # Configuration classes and properties
│ │ ├── constant # Constants used in the application
│ │ ├── enums # Enums used in the application
│ │ ├── exception # Custom exceptions used in the application
│ │ ├── shared # Resources like dto, utils, etc. used in the application
│ │ ├── task # Scheduled tasks and cron jobs used in the application
│ │ └── web # Web layer implementation
│ ├── resources
│ │ ├── i18n # I18n property files, comes with 'en', 'fr', 'es' and 'zn_CN'
│ │ ├── static
│ │ │ ├── css
│ │ │ ├── fonts
│ │ │ ├── images
│ │ │ └── js
│ │ │ └── form-validation
│ │ └── templates
│ │ ├── common
│ │ │ └── email
│ │ ├── email
│ │ ├── error
│ │ └── user
│ └── scripts # Scripts used in the application as part of docker build, etc.
└── test
├── java
│ └── com
│ └── kavun
│ ├── backend
│ ├── config
│ ├── shared
│ └── web
└── resources
Note: In Permission entity, the entityId field represents the ID of either a Role or a User, depending on the EntityType. This design allows for flexible permission assignments, enabling both role-based and user-specific permissions within the system.
Please refer to the Roadmap for the project roadmap and future plans.
In the Kavun project, we follow a structured development workflow to ensure efficient collaboration and code management. This workflow includes the following key components: branching strategy, versioning, and commit message conventions. By following these guidelines, we aim to maintain a clean and organized codebase that is easy to manage and contribute to. For more information, please refer to the Contributing Guide document.
Thanks to the following people who have contributed to this project:
- Yunus Emre Alpu - Creator and Maintainer