Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your development machine:

Java JDK 21

Required for running and building the application

Apache Maven

Build automation and dependency management

PostgreSQL

Primary database for the application

Git

Version control system

​
Clone the Repository

Start by cloning the project repository: 
git clone https://github.com/Raven-Training/jc-java-training.git
cd jc-java-training

​
Database Configuration

​
Create PostgreSQL Database

Create a new PostgreSQL database named book: 
CREATE DATABASE book;

​
Configure Application Properties

The application uses environment variables for database configuration. Set the following environment variables: 
export db_url="jdbc:postgresql://localhost:5432/book"
export db_username="your_postgres_username"
export db_password="your_postgres_password"
The application uses spring.jpa.hibernate.ddl-auto=create-drop in development mode, which will recreate the database schema on each startup.

​
JWT Configuration

Configure JWT security by setting these environment variables: 
export user_jwt="your_jwt_user_identifier"
export key_jwt="your_secret_jwt_key"
Never commit sensitive credentials to version control. Use environment variables or a secure secrets management solution.

​
Dependencies Overview

The project uses the following key dependencies (defined in pom.xml):

​
Core Dependencies

DependencyVersionPurpose
Spring Boot3.5.3Application framework
Java21Programming language
PostgreSQL DriverLatestDatabase connectivity
Spring Data JPA3.5.3Database abstraction layer

​
Additional Libraries

LibraryVersionPurpose
MapStruct1.6.3Object mapping
Lombok1.18.32Boilerplate code reduction
SpringDoc OpenAPI2.8.9API documentation (Swagger)
Spring Security3.5.3Authentication & authorization
Auth0 JWT4.4.0JWT token handling
JaCoCo0.8.13Code coverage analysis

​
Build the Project

​
Using Maven Wrapper

The project includes a Maven wrapper for consistent builds: 
./mvnw clean install

​
Using System Maven

If you have Maven installed globally: 
mvn clean install
The build process includes:
  • Compilation of Java sources
  • Running all unit and integration tests
  • Generation of MapStruct implementations
  • Code coverage analysis with JaCoCo
  • Packaging the application as a JAR file

​
MapStruct Configuration

The project uses MapStruct for object mapping between layers. The annotation processor is configured in pom.xml: 
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.32</version>
            </path>
            <path>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.6.3</version>
            </path>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok-mapstruct-binding</artifactId>
                <version>0.2.0</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>
The order of annotation processors is important! Lombok must be processed before MapStruct to ensure proper code generation.

​
Running the Application

​
Development Mode

Run the application using Spring Boot Maven plugin: 
./mvnw spring-boot:run
The application will start on port 8081 by default.

​
Verify Installation

Once the application is running, verify it’s working: 
curl http://localhost:8081/swagger-ui/index.html
You should see the Swagger UI interface for exploring the API.

​
IDE Setup

​
IntelliJ IDEA

  1. Install Lombok Plugin: Go to Settings → Plugins → Search for “Lombok” → Install
  2. Enable Annotation Processing: Settings → Build, Execution, Deployment → Compiler → Annotation Processors → Enable annotation processing
  3. Import Project: File → Open → Select pom.xml

​
Eclipse

  1. Install Lombok: Download lombok.jar and run java -jar lombok.jar
  2. Import Maven Project: File → Import → Maven → Existing Maven Projects

​
VS Code

  1. Install Extensions:
    • Language Support for Java
    • Spring Boot Extension Pack
    • Lombok Annotations Support
  2. Open Project: File → Open Folder → Select project directory

​
Development Tools

​
Spring Boot DevTools

The project includes Spring Boot DevTools for automatic restart: 
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>
DevTools automatically restarts the application when class files change.

​
Next Steps

Project Structure

Learn about the application architecture and package organization

Testing

Understand the testing strategy and how to run tests

API Endpoints

Explore the available API endpoints

Authentication

Learn about JWT authentication implementation

​
Troubleshooting

Run mvn clean compile to regenerate MapStruct implementations. Ensure annotation processing is enabled in your IDE.
Verify PostgreSQL is running and the environment variables are set correctly:
echo $db_url
echo $db_username
Change the port in application.properties:
server.port=8082
Ensure Lombok is properly installed in your IDE and annotation processing is enabled.

Build docs developers (and LLMs) love

Get started for freeTalk to us