🚧 Under construction 🚧

Final Store

A comprehensive Java Spring Boot e-commerce store API.

Project Links

• Roadmap
• Database design

Documentation

• Development Guide - Hot reload, debugging, and workflow
• Docker Guide - Detailed Docker documentation
• Quick Start Guide - Quick reference
• Stripe Testing Guide - Testing payments without a frontend

Prerequisites

Choose one of the following setup options:

Option 1: Local Setup (full control)

Required:

• Java 21
• MySQL 8.0

Installation (macOS):

# Install Java 21
brew install openjdk@21

# Install MySQL
brew install mysql
brew services start mysql

Installation (Ubuntu):

# Install Java 21
sudo apt update
sudo apt install openjdk-21-jdk

# Install MySQL
sudo apt install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql

Note: If there are multiple jdk versions on the machine, and you want to run from terminal, use 21.

# .bashrc
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

then

./mvnw spring-boot:run

Optional:

• DBeaver for database management
• IntelliJ IDEA for development

Option 2: Docker Setup (easiest, OS-agnostic)

Required:

• Docker
• Docker Compose

Use this option if:

• You don't want to install Java / MySQL locally
• You want an isolated environment

Setup Instructions

Local Setup

1. Configure MySQL

# Connect to MySQL
mysql -u root

# Set root password and create database
ALTER USER 'root'@'localhost' IDENTIFIED BY '0000';
FLUSH PRIVILEGES;
CREATE DATABASE my_store;
EXIT;

2. Configure Environment Variables

# Copy environment template
cp .env.example .env

# Generate JWT secret
openssl rand -base64 64

# Edit .env and set JWT_SECRET to the generated value

3. Configure IntelliJ IDEA

Set up JDK:

1. Go to File > Project Structure > Project
2. Set SDK to Java 21

Find JDK location if needed:

# macOS
/usr/libexec/java_home -V

# Ubuntu
ls /usr/lib/jvm

Common locations:

• macOS: /Library/Java/JavaVirtualMachines/openjdk-21.jdk/Contents/Home
• Ubuntu: /usr/lib/jvm/java-21-openjdk-amd64/

Set up database connection:

1. Open Database tab (right side)
2. Click + > Data Source > MySQL
3. Configure:
   • Host: localhost
   • Port: 3306
   • User: root
   • Password: 0000
   • Database: my_store

Run migrations:

1. Open Maven tool window
2. Navigate to Plugins > flyway
3. Run flyway:migrate

Create run configuration:

1. Run > Edit Configurations
2. Add new Spring Boot configuration
3. Select main class: com.vpe.finalstore.FinalStoreApplication
4. Run the application

Alternative: Use Make commands:

make start  # Start the application locally
make build  # Build the application locally

4. Seed the database

After you run the app you can seed the database with test data by running the following command:

curl -X POST -H "Content-Type: application/json" -d '{"cleanStart": true, "userCount": 100, "productCount": 50, "orderCount": 200}' http://localhost:8080/api/seeder/db-seed

or via Swagger UI: http://localhost:8080/swagger-ui.html#. Look for /api/seeder/db-seed and /api/seeder/clean

5. Access the Application

• API: http://localhost:8080
• Swagger UI: http://localhost:8080/swagger-ui.html

Docker Setup

Docker Compose sets up both the application and MySQL database with a single command.

1. Configure Environment Variables

# Copy environment template
cp .env.example .env

# Generate JWT secret
openssl rand -base64 64

# Edit .env and set JWT_SECRET to the generated value

2. Start the Application

Development mode with Docker (hot reload):

make start-dev

Features:

• Automatically reloads when you change Java files
• No rebuild needed after code changes
• Debug port available on 5005
• Useful when you don't have Java installed locally

Production mode with Docker:

make start-prod

Note: In production mode, rebuild after code changes:

make build-prod

All available commands:

make help

3. Seed the Database

Connect to MySQL:

# From Docker container
docker exec -it final-store-mysql mysql -uroot -p0000 my_store

# From host machine
mysql -h 127.0.0.1 -P 3307 -u root -p0000 my_store

Run the seed script from here

4. Access the Application

• API: http://localhost:8080
• Swagger UI: http://localhost:8080/swagger-ui.html

Additional Information

Migrations

Docker Setup: Flyway migrations run automatically when the application starts. The database schema is created on first startup.

Local Setup: Run migrations manually using:

make migrate       # Run migrations
make info-migrate  # Check migration status

Troubleshooting: If migrations fail, see DEVELOPMENT.md for repair instructions.

Common Tasks

View logs (Docker):

make logs-prod     # Production mode
make logs-dev      # Development mode

Stop the application (Docker):

make stop-prod     # Production mode
make stop-dev      # Development mode

Database shell (Docker):

make db-shell      # Production mode
make db-shell-dev  # Development mode