Installation

This guide covers everything you need to know to install and configure TechStore in both development and production environments.

Prerequisites

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

Required Software

Java 21

TechStore is built with Java 21 and Spring Boot 3.4.1

java -version
# Should show: openjdk version "21.x.x"

MySQL 8.0+

Primary database (PostgreSQL also supported)

mysql --version
# Should show: mysql Ver 8.0.x

Maven 3.6+

Build tool (or use included wrapper)

mvn -version
# Or use ./mvnw (included)

Git

Version control for cloning the repository

git --version

System Requirements

RAM: 4GB minimum, 8GB recommended
Disk Space: 500MB for application + database
OS: Linux, macOS, or Windows

Installation Steps

1. Install Java 21

Ubuntu/Debian
macOS
Windows

sudo apt update
sudo apt install openjdk-21-jdk
java -version

brew install openjdk@21
echo 'export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
java -version

Download OpenJDK 21
Run the installer
Set JAVA_HOME environment variable
Add %JAVA_HOME%\bin to PATH

2. Install MySQL

Ubuntu/Debian
macOS
Windows

sudo apt update
sudo apt install mysql-server
sudo systemctl start mysql
sudo mysql_secure_installation

brew install mysql
brew services start mysql
mysql_secure_installation

3. Database Setup

Create Database

Connect to MySQL and create the database:

mysql -u root -p

CREATE DATABASE tienda_digital;
CREATE DATABASE tienda_digital_test; -- Optional: for testing

-- Create dedicated user (recommended for production)
CREATE USER 'techstore'@'localhost' IDENTIFIED BY 'secure_password_here';
GRANT ALL PRIVILEGES ON tienda_digital.* TO 'techstore'@'localhost';
GRANT ALL PRIVILEGES ON tienda_digital_test.* TO 'techstore'@'localhost';
FLUSH PRIVILEGES;

EXIT;

Always use strong passwords in production environments. Never commit database credentials to version control.

Schema Initialization

TechStore uses Hibernate DDL Auto mode, which automatically creates and updates database tables based on your entity classes.

The spring.jpa.hibernate.ddl-auto=update setting means:

Tables are created automatically on first run
Schema changes are applied on application restart
Existing data is preserved

Main tables created:

usuarios - User accounts with authentication
roles - User role definitions (ADMIN, USER)
usuarios_roles - Many-to-many relationship
productos - Product catalog
categorias - Product categories
pedidos - Customer orders
pedido_detalle - Order line items
carrito - Shopping cart sessions
carrito_item - Cart items
producto_imagen - Product image gallery

4. Application Configuration

Basic Configuration

Create or edit src/main/resources/application.properties:

# Application Name
spring.application.name=tienda-online

# Database Configuration
spring.datasource.url=jdbc:mysql://localhost:3306/tienda_digital?serverTimezone=UTC
spring.datasource.username=techstore
spring.datasource.password=secure_password_here
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# JPA / Hibernate Settings
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL8Dialect

# Logging Configuration
logging.level.org.springframework.security=INFO
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

Email Service Configuration (Optional but Recommended)

TechStore includes an email service for user verification and password recovery:

# Gmail SMTP Configuration
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=your-email@gmail.com
spring.mail.password=your-16-char-app-password

# SMTP Properties
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true
spring.mail.properties.mail.smtp.ssl.trust=smtp.gmail.com

# Brand Customization
app.shop.name=TechStore
app.shop.support-email=support@techstore.com

# Sender Identity
spring.mail.properties.mail.smtp.from=your-email@gmail.com
spring.mail.properties.mail.debug=false

Gmail Users: Generate an App Password at myaccount.google.com/apppasswords. Regular passwords won’t work with SMTP.

Security Configuration

TechStore uses RSA asymmetric encryption for JWT tokens. Keys are generated automatically on startup, but you can configure:

# JWT Configuration (optional - defaults work fine)
jwt.expiration-hours=24

# CORS Configuration (adjust for your frontend)
cors.allowed-origins=http://localhost:3000,https://yourdomain.com

The SecurityConfig class (src/main/java/ab/tienda_online/security/SecurityConfig.java:143-151) automatically generates 2048-bit RSA keys for secure JWT signing.

5. Build the Application

Using Maven Wrapper (recommended):

# Unix/macOS
./mvnw clean install

# Windows
mvnw.cmd clean install

Using system Maven:

mvn clean install

The first build downloads all dependencies (~200MB). Subsequent builds are much faster.

6. Run the Application

Development Mode

# With Maven Wrapper
./mvnw spring-boot:run

# With system Maven
mvn spring-boot:run

# With Java directly (after building)
java -jar target/tienda-online-0.0.1-SNAPSHOT.jar

The application starts on http://localhost:8080 by default.

Production Mode

For production, build an executable JAR and run with production profile:

# Build production JAR
./mvnw clean package -DskipTests

# Run with production settings
java -jar -Dspring.profiles.active=prod target/tienda-online-0.0.1-SNAPSHOT.jar

Create application-prod.properties with production-specific settings (secure passwords, external database, etc.)

Run as System Service (Linux)

Create /etc/systemd/system/techstore.service:

[Unit]
Description=TechStore E-Commerce Application
After=syslog.target network.target mysql.service

[Service]
User=techstore
ExecStart=/usr/bin/java -jar /opt/techstore/tienda-online.jar
SuccessExitStatus=143
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable techstore
sudo systemctl start techstore
sudo systemctl status techstore

Development vs Production

Development Settings

# Show SQL queries for debugging
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

# Detailed security logs
logging.level.org.springframework.security=DEBUG

# Auto-update schema
spring.jpa.hibernate.ddl-auto=update

# Enable DevTools for hot reload
spring.devtools.restart.enabled=true

Production Settings

# Disable SQL logging
spring.jpa.show-sql=false

# Minimal logging
logging.level.org.springframework.security=WARN

# Validate schema only (don't auto-update)
spring.jpa.hibernate.ddl-auto=validate

# Use connection pooling
spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.minimum-idle=5

# Disable DevTools
spring.devtools.restart.enabled=false

Never use ddl-auto=update in production! Use database migration tools like Flyway or Liquibase instead.

Verify Installation

Check that the application is running correctly:

# Health check
curl http://localhost:8080/api/productos

# Should return 200 OK with product list (may be empty initially)

Troubleshooting

Port 8080 already in use

Error: Web server failed to start. Port 8080 was already in use.Solution:Change the port in application.properties:

server.port=8081

Or kill the process using port 8080:

# Find process
lsof -i :8080

# Kill it
kill -9 <PID>

Database connection refused

Error: Communications link failure or Connection refusedSolution:

Verify MySQL is running:

sudo systemctl status mysql
# or
brew services list

Check connection details in application.properties:

spring.datasource.url=jdbc:mysql://localhost:3306/tienda_digital?serverTimezone=UTC

Test connection manually:

mysql -u techstore -p -h localhost tienda_digital

Verify user permissions:

SHOW GRANTS FOR 'techstore'@'localhost';

Java version mismatch

Error: Unsupported class file major version 65Solution:TechStore requires Java 21. Check your version:

java -version
javac -version

If you have multiple Java versions, set JAVA_HOME:

export JAVA_HOME=/path/to/java-21
export PATH=$JAVA_HOME/bin:$PATH

JWT token generation fails

Error: IllegalStateException during RSA key generationSolution:This is rare but can happen if your JVM lacks cryptography libraries. Ensure you’re using a full JDK (not JRE):

java -version
# Should show "OpenJDK" not just "Java"

The RSA key generation happens in SecurityConfig.java:143-151.

Email sending fails

Error: Authentication failed or Could not send mailSolutions:

Gmail App Password: Don’t use your regular Gmail password. Generate an App Password:
- Go to myaccount.google.com/apppasswords
- Generate a 16-character password
- Use this in application.properties

Check SMTP settings:

spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.properties.mail.smtp.starttls.enable=true

Enable debug mode:
```
spring.mail.properties.mail.debug=true
```

Test with curl:

curl -v --url 'smtps://smtp.gmail.com:465' --ssl-reqd \
  --mail-from 'your-email@gmail.com' \
  --user 'your-email@gmail.com:your-app-password'

Maven build fails

Error: Failed to execute goal or dependency issuesSolutions:

Clear Maven cache:

rm -rf ~/.m2/repository
./mvnw clean install

Use Maven wrapper instead of system Maven:
```
./mvnw clean install
```
Check network connectivity (Maven downloads dependencies)
Verify pom.xml is not corrupted:
```
./mvnw validate
```

Hibernate schema update errors

Error: Table doesn't exist or Column not foundSolution:

Development: Drop and recreate database:

DROP DATABASE tienda_digital;
CREATE DATABASE tienda_digital;

Production: Use manual migration:
```
spring.jpa.hibernate.ddl-auto=validate
```
Then apply schema changes manually.
Check entity classes match database:
- Usuario.java:43-49 - User roles relationship
- Producto.java:42-44 - Product category relationship

CORS errors from frontend

Error: Access to fetch blocked by CORS policySolution:Add your frontend URL to CORS configuration in SecurityConfig.java:66-73:

cfg.setAllowedOrigins(List.of(
    "http://localhost:3000",  // React default
    "http://localhost:5173",  // Vite default
    "https://yourdomain.com"  // Production
));

Or in application.properties:

cors.allowed-origins=http://localhost:3000,https://yourdomain.com

Next Steps

Quickstart Guide

Make your first API request in 5 minutes

Configuration

Advanced configuration options

API Reference

Explore all available endpoints

Deployment

Deploy to production (Docker, AWS, etc.)

Additional Resources

Having issues? Check the GitHub Issues or reach out to the community.

Get Started

Core Features

User Guides

Prerequisites

Required Software

Java 21

MySQL 8.0+

Maven 3.6+

Git

System Requirements

Installation Steps

1. Install Java 21

2. Install MySQL

3. Database Setup

Create Database

Schema Initialization

4. Application Configuration

Basic Configuration

Email Service Configuration (Optional but Recommended)

Security Configuration

5. Build the Application

6. Run the Application

Development Mode

Production Mode

Run as System Service (Linux)

Development vs Production

Development Settings

Production Settings

Verify Installation

Troubleshooting

Next Steps

Quickstart Guide

Configuration

API Reference

Deployment

Additional Resources

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

​Prerequisites

​Required Software

Java 21

MySQL 8.0+

Maven 3.6+

Git

​System Requirements

​Installation Steps

​1. Install Java 21

​2. Install MySQL

​3. Database Setup

​Create Database

​Schema Initialization

​4. Application Configuration

​Basic Configuration

​Email Service Configuration (Optional but Recommended)

​Security Configuration

​5. Build the Application

​6. Run the Application

​Development Mode

​Production Mode

​Run as System Service (Linux)

​Development vs Production

​Development Settings

​Production Settings

​Verify Installation

​Troubleshooting

​Next Steps

Quickstart Guide

Configuration

API Reference

Deployment

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Required Software

System Requirements

Installation Steps

1. Install Java 21

2. Install MySQL

3. Database Setup

Create Database

Schema Initialization

4. Application Configuration

Basic Configuration

Email Service Configuration (Optional but Recommended)

Security Configuration

5. Build the Application

6. Run the Application

Development Mode

Production Mode

Run as System Service (Linux)

Development vs Production

Development Settings

Production Settings

Verify Installation

Troubleshooting

Next Steps

Additional Resources