Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Java 17 or higher
  • Maven 3.6+ (or use the included Maven wrapper)
  • MySQL 8.0+
  • Git
This application uses Spring Boot 3.5.7 with Java 17. Make sure your JAVA_HOME environment variable is properly configured.

​
Quick Setup

Follow these steps to get your API running locally:
1

Clone the Repository

Clone the project to your local machine:
git clone <your-repository-url>
cd demo
2

Configure MySQL Database

Create a MySQL database for the application:
CREATE DATABASE ecommerce;
Update the database credentials in src/main/resources/application.properties:
spring.application.name=demo
spring.datasource.url=jdbc:mysql://localhost:3306/ecommerce?serverTimezone=UTC
spring.datasource.username=root
spring.datasource.password=your_password
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.jpa.hibernate.ddl-auto=update
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL8Dialect
Make sure to replace your_password with your actual MySQL root password. Never commit credentials to version control.
3

Build the Application

Use Maven to build the project and download dependencies:
# Using Maven wrapper (recommended)
./mvnw clean install

# Or using system Maven
mvn clean install
This command will:
  • Download all required dependencies
  • Compile the source code
  • Run tests
  • Package the application
4

Run the Application

Start the Spring Boot application:
# Using Maven wrapper
./mvnw spring-boot:run

# Or using system Maven
mvn spring-boot:run
The application will start on http://localhost:8080 by default.
The application uses spring.jpa.hibernate.ddl-auto=update, which means database tables will be created automatically on first run.
5

Verify the Installation

Once the application is running, you should see output similar to:
Started DemoApplication in X.XXX seconds
The API is now ready to accept requests!

​
Test Your First API Request

Now that your API is running, let’s test it with some example requests: 
curl -X POST http://localhost:8080/registro \
  -H "Content-Type: application/json" \
  -d '{
    "usuario": "testuser",
    "contrasena": "Password123"
  }'

​
Expected Response

A successful user registration will return: 
{
  "id": 1,
  "usuario": "testuser",
  "contrasena": {
    "value": "Password123"
  }
}
Password validation requires:
  • Minimum 8 characters
  • Maximum 64 characters
  • At least one letter
  • At least one number
These rules are enforced by the ContrasenaVO (Value Object) in the domain layer.

​
Project Structure Overview

After cloning, your project structure will look like this: 
demo/
├── src/
│   ├── main/
│   │   ├── java/com/example/demo/
│   │   │   ├── DemoApplication.java          # Main application entry point
│   │   │   ├── core/                         # Shared infrastructure
│   │   │   ├── usuario/                      # User module
│   │   │   │   ├── application/              # Use cases & handlers
│   │   │   │   ├── domain/                   # Business logic
│   │   │   │   └── infrastructure/           # Controllers & repositories
│   │   │   └── producto/                     # Product module
│   │   └── resources/
│   │       └── application.properties        # Configuration
│   └── test/
├── pom.xml                                   # Maven dependencies
├── mvnw                                      # Maven wrapper (Unix)
└── mvnw.cmd                                  # Maven wrapper (Windows)

​
Key Dependencies

The application uses the following core dependencies: 
<!-- Spring Boot Starters -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<!-- MySQL Driver -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
</dependency>

<!-- Lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>

​
Next Steps

Architecture Overview

Learn about the clean architecture and CQRS patterns used in this project

User API Endpoints

Explore user registration and login endpoints

Authentication Guide

Understand how user authentication works

User Model

Deep dive into the user domain model

​
Troubleshooting

​
Application won’t start

Database connection errors:
  • Verify MySQL is running: mysql -u root -p
  • Check credentials in application.properties
  • Ensure the ecommerce database exists
Port already in use:
  • Change the default port by adding to application.properties: 
    server.port=8081
Java version mismatch:
  • Check your Java version: java -version
  • Ensure it’s Java 17 or higher
  • Set JAVA_HOME: export JAVA_HOME=/path/to/java17

​
Maven build failures

  • Clear Maven cache: ./mvnw clean
  • Update dependencies: ./mvnw dependency:resolve
  • Check internet connection for dependency downloads
For more detailed troubleshooting, check the application logs in the console output or enable debug logging by adding logging.level.root=DEBUG to your application.properties.

Build docs developers (and LLMs) love

Get started for freeTalk to us