Installation

This guide will walk you through installing and running Portfolio Hub API on your development environment.

Prerequisites

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

Java 21 (JDK)

Required for running Spring Boot 3.5.6

Maven 3.9+

Build automation and dependency management

MySQL 8.0+

Primary database for portfolio data

Google Cloud Account

For Google Drive file uploads (optional)

Portfolio Hub API uses Spring Boot 3.5.6 which requires Java 21. Make sure you have the correct JDK version installed.

Installation Steps

Verify Java Installation

Check that Java 21 is installed and set as your default JDK:

java -version

You should see output indicating Java version 21:

openjdk version "21.0.x" 2024-xx-xx
OpenJDK Runtime Environment (build 21.0.x+xx)
OpenJDK 64-Bit Server VM (build 21.0.x+xx, mixed mode, sharing)

Installing Java 21

On macOS (using Homebrew):

brew install openjdk@21

On Ubuntu/Debian:

sudo apt update
sudo apt install openjdk-21-jdk

On Windows: Download and install from Oracle or Adoptium.

Verify Maven Installation

Check that Maven 3.9+ is installed:

mvn -version

Expected output:

Apache Maven 3.9.x
Maven home: /path/to/maven
Java version: 21.0.x

Installing Maven

On macOS (using Homebrew):

brew install maven

On Ubuntu/Debian:

sudo apt update
sudo apt install maven

On Windows: Download from Apache Maven and add to PATH.

Clone the Repository

Clone the Portfolio Hub API repository to your local machine:

git clone <repository-url>
cd portfolio-hub-api

Install Dependencies

Maven will automatically download all required dependencies based on the pom.xml configuration:

mvn clean install

This command will:

Download all Spring Boot dependencies
Compile the source code
Run unit tests
Package the application

The first build may take several minutes as Maven downloads all dependencies.

Set Up MySQL Database

Create the database schema that Portfolio Hub API will use:

CREATE SCHEMA IF NOT EXISTS `studiostkoh.portafolio`;

Do not create tables manually. Flyway migrations will automatically create and manage the database schema on first startup.

See the Database Setup guide for detailed MySQL configuration.

Configure Environment Variables

Portfolio Hub API requires several environment variables to be set. Create a .env file or export these variables:

# Database Configuration
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_DATABASE=studiostkoh.portafolio
export MYSQL_USER=your_username
export MYSQL_PASSWORD=your_password

# JWT Configuration
export JWT_TOKEN=your_secret_key_min_256_bits
export JWT_EXPIRATION_TIME=60

# CORS Configuration
export CORS_ALLOWED_ORIGINS=http://localhost:3000

Google Drive and SMTP configuration are optional for basic setup. See the Configuration guide for all available options.

Run the Application

Start the Portfolio Hub API using Maven:

./mvnw spring-boot:run

Or if you’re on Windows:

mvnw.cmd spring-boot:run

The application will start on port 8080 by default. You should see output similar to:

Started PortfolioApplication in 5.234 seconds (process running for 5.567)

Verify Installation

Test that the API is running by accessing the Swagger UI documentation:

http://localhost:8080/swagger-ui/index.html

You should see the interactive API documentation with all available endpoints.

If you see the Swagger UI, congratulations! Portfolio Hub API is successfully installed.

Key Dependencies

Portfolio Hub API includes the following major dependencies:

Dependency	Version	Purpose
Spring Boot	3.5.6	Core framework
Spring Security	6.x	JWT authentication
Spring Data JPA	3.x	Database operations
MySQL Connector	Latest	MySQL database driver
Flyway	Latest	Database migrations
JWT (jjwt)	0.12.6	JSON Web Token handling
MapStruct	1.6.3	DTO mapping
Lombok	1.18.40	Reduce boilerplate code
SpringDoc	2.8.14	OpenAPI/Swagger documentation
Google Drive API	v3	File upload integration

Build Configuration

The project uses annotation processors for Lombok and MapStruct. These are configured in the pom.xml:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.6.3</version>
            </path>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.40</version>
            </path>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok-mapstruct-binding</artifactId>
                <version>0.2.0</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Running in Production

To build a production-ready JAR file:

mvn clean package -DskipTests

This creates an executable JAR in the target/ directory:

java -jar target/portfolio-0.5-M1.jar

Always set production environment variables before running in production. Never use default or development credentials.

Troubleshooting

Port 8080 already in use

Change the port by setting the server.port property:

./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8081

Or add to application.properties:

server.port=8081

MySQL connection refused

Verify that:

MySQL server is running
The database schema exists
Environment variables are correctly set
User has proper permissions

Test connection:

mysql -h localhost -u your_username -p

Flyway migration failures

If migrations fail, check:

Database user has CREATE/ALTER permissions
The schema exists: CREATE SCHEMA IF NOT EXISTS \studiostkoh.portafolio`;`
No manual table modifications have been made

To reset (development only):

DROP SCHEMA `studiostkoh.portafolio`;
CREATE SCHEMA `studiostkoh.portafolio`;

Java version mismatch

Portfolio Hub API requires Java 21. If you have multiple Java versions:Set JAVA_HOME:

export JAVA_HOME=/path/to/java-21

Verify:

$JAVA_HOME/bin/java -version

Next Steps

Configuration

Configure environment variables and application properties

Database Setup

Learn about the database schema and Flyway migrations

Authentication

Set up JWT authentication and create your first user

API Reference

Explore all available API endpoints

Get Started

Setup

Guides

Deployment

Prerequisites

Java 21 (JDK)

Maven 3.9+

MySQL 8.0+

Google Cloud Account

Installation Steps

Key Dependencies

Build Configuration

Running in Production

Troubleshooting

Next Steps

Configuration

Database Setup

Authentication

API Reference

Build docs developers (and LLMs) love

Get Started

Setup

Guides

Deployment

​Prerequisites

Java 21 (JDK)

Maven 3.9+

MySQL 8.0+

Google Cloud Account

​Installation Steps

​Key Dependencies

​Build Configuration

​Running in Production

​Troubleshooting

​Next Steps

Configuration

Database Setup

Authentication

API Reference

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

Key Dependencies

Build Configuration

Running in Production

Troubleshooting

Next Steps