Skip to main content
This guide provides detailed instructions for installing and configuring the Library Management API on your local development environment.

​
System Requirements

Before installing the application, ensure your system meets the following requirements:

​
Required Software

Java JDK 21

The application is built with Java 21 and requires this specific version.

Apache Maven

Maven 3.6+ is required for building and managing dependencies.

PostgreSQL

PostgreSQL 12+ is required for data persistence.

Git

Git is needed to clone the repository.

​
Hardware Requirements

  • RAM: Minimum 2GB, recommended 4GB+
  • Disk Space: At least 500MB for the application and dependencies
  • CPU: Any modern processor (dual-core or better recommended)

​
Installation Steps

1

Install Java JDK 21

Download and install Java JDK 21 from Oracle or OpenJDK.Verify the installation:
java -version
Expected output:
java version "21.0.x"
Java(TM) SE Runtime Environment (build 21.0.x+xx)
Make sure JAVA_HOME is set correctly in your environment variables.
2

Install Apache Maven

Download Maven from the official website and follow the installation instructions for your operating system.Verify the installation:
mvn -version
Expected output:
Apache Maven 3.9.x
Maven home: /path/to/maven
Java version: 21.0.x
3

Install PostgreSQL

Install PostgreSQL from the official website or use your system’s package manager:
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
Verify PostgreSQL is running:
psql --version
4

Clone the repository

Clone the project repository from GitHub:
git clone https://github.com/Raven-Training/jc-java-training.git
cd jc-java-training

​
Database Configuration

1

Create the database

Connect to PostgreSQL and create the application database:
psql -U postgres
Then in the PostgreSQL console:
CREATE DATABASE book;
You can verify the database was created:
\l
Exit the PostgreSQL console:
\q
2

Configure database credentials

The application uses environment variables for database configuration. These are referenced in src/main/resources/application.properties:
spring.datasource.url=${db_url}
spring.datasource.username=${db_username}
spring.datasource.password=${db_password}
spring.datasource.driver-class-name=org.postgresql.Driver
Set the required environment variables:
export db_url="jdbc:postgresql://localhost:5432/book"
export db_username="postgres"
export db_password="your_password"
Replace your_password with your actual PostgreSQL password. Never commit credentials to version control.
3

Understand the database auto-configuration

The application is configured with spring.jpa.hibernate.ddl-auto=create-drop in application.properties:
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect
spring.jpa.hibernate.ddl-auto=create-drop
create-drop: The database schema is automatically created when the application starts and dropped when it stops. This is useful for development but should be changed to update or validate for production.
For production environments, change this to:
spring.jpa.hibernate.ddl-auto=update

​
Application Configuration

1

Configure JWT security

The application uses JWT (JSON Web Token) for authentication. Configure the JWT settings using environment variables:
export user_jwt="library-api-user"
export key_jwt="your-secret-jwt-key-at-least-256-bits-long"
These variables are referenced in application.properties:
security.jwt.user.generator=${user_jwt}
security.jwt.key.private=${key_jwt}
The key_jwt must be a secure random string of at least 256 bits (32 characters). Use a strong, randomly generated key for production environments.
You can generate a secure key using:
openssl rand -base64 32
2

Configure server port (optional)

The application runs on port 8081 by default:
server.port=8081
To change the port, you can:
  • Modify application.properties
  • Set an environment variable: export server.port=9090
  • Use a command-line argument: mvn spring-boot:run -Dserver.port=9090
3

Review application configuration

The complete application.properties file includes:
spring.application.name=training

# PostgreSQL Database Configuration
spring.datasource.url=${db_url}
spring.datasource.username=${db_username}
spring.datasource.password=${db_password}

# PostgreSQL Driver
spring.datasource.driver-class-name=org.postgresql.Driver

# Hibernate/JPA Configurations
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect
spring.jpa.hibernate.ddl-auto=create-drop

server.port=8081

security.jwt.user.generator=${user_jwt}
security.jwt.key.private=${key_jwt}
All environment variables must be set before starting the application, or it will fail to start.

​
Building and Running

1

Install dependencies

Download all project dependencies using Maven:
mvn clean install
This command will:
  • Clean previous builds
  • Download dependencies from Maven Central
  • Compile the source code
  • Run tests
  • Package the application as a JAR file
The build process may take a few minutes the first time as Maven downloads dependencies.
2

Run the application

Start the Spring Boot application:
mvn spring-boot:run
Alternatively, run the packaged JAR file:
java -jar target/training-0.0.1-SNAPSHOT.jar
Make sure all environment variables are set in your current shell session before running the application.
3

Verify the application is running

Once started, you should see output similar to:
Started TrainingApplication in X.XXX seconds
Test the application by accessing:
curl http://localhost:8081/swagger-ui/index.html
Or open the URL in your browser to access the Swagger UI.

​
Project Dependencies

The application uses the following key dependencies (from pom.xml):

Spring Boot 3.5.3

Core framework for building the REST API

Spring Security

Security framework with JWT authentication

Spring Data JPA

Data persistence and ORM with Hibernate

PostgreSQL Driver

JDBC driver for PostgreSQL connectivity

Auth0 JWT 4.4.0

JWT token generation and validation

MapStruct 1.6.3

Object mapping between DTOs and entities

Lombok 1.18.32

Reduces boilerplate code with annotations

SpringDoc OpenAPI 2.8.9

Generates Swagger/OpenAPI documentation

​
Development Tools

​
Hot Reload

The application includes Spring Boot DevTools for automatic restart during development: 
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>
Changes to Java files will automatically trigger an application restart.

​
Testing

Run the test suite: 
mvn test
Generate code coverage report with JaCoCo: 
mvn clean test jacoco:report
The coverage report will be available at target/site/jacoco/index.html.
The project is configured with an 80% code coverage requirement at the package level.

​
Troubleshooting

Error: Could not resolve placeholder 'db_url' in value "${db_url}"Solution: Ensure all required environment variables are set in your current shell session:
  • db_url
  • db_username
  • db_password
  • user_jwt
  • key_jwt
Verify with:
echo $db_url  # Linux/macOS
echo %db_url%  # Windows CMD
echo $env:db_url  # Windows PowerShell
Error: Connection to localhost:5432 refusedSolution:
  1. Verify PostgreSQL is running: 
    sudo systemctl status postgresql  # Linux
brew services list  # macOS
  2. Check that PostgreSQL is listening on port 5432
  3. Verify your credentials are correct
  4. Ensure the book database exists
Error: Port 8081 is already in useSolution: Either stop the other application using port 8081, or change the application port:
mvn spring-boot:run -Dserver.port=9090
Error: Various Maven compilation errorsSolution:
  1. Ensure you’re using Java 21: 
    java -version
  2. Clean the Maven cache: 
    mvn clean
  3. Force update dependencies: 
    mvn clean install -U
Error: Token signature verification failedSolution: Ensure the key_jwt environment variable is:
  1. Set before starting the application
  2. At least 256 bits (32 characters) long
  3. The same value used to generate the tokens
The key must remain consistent across application restarts for existing tokens to remain valid.

​
Next Steps

Quick Start

Follow the quick start guide to make your first API calls

Architecture

Learn about the application’s layered architecture

Authentication

Understand JWT authentication and security

API Reference

Explore all available API endpoints

​
Production Deployment

For production deployments, consider:
Important Production Changes:
  1. Change spring.jpa.hibernate.ddl-auto from create-drop to update or validate
  2. Use a secure, randomly generated JWT key (minimum 256 bits)
  3. Store credentials securely (use secrets management, not environment variables)
  4. Configure proper database connection pooling
  5. Enable HTTPS/TLS
  6. Set up proper logging and monitoring
  7. Review and configure security headers
  8. Disable Swagger UI in production or protect it with authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us