Quickstart

Prerequisites

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

Java Development Kit

JDK 17 or higherRequired for running Spring Boot microservices

MySQL Database

MySQL 8.0 or higherDatabase server for all microservices

Maven Build Tool

Maven 3.6+For building Spring Boot projects

Node.js & npm

Node.js 18+ and npmRequired for Angular frontend

System Requirements: At least 8GB RAM recommended for running all services simultaneously, 4GB minimum for development.

Database Setup

Start MySQL Server

Ensure your MySQL server is running on the default port 3306.

# Check MySQL status (Linux/Mac)
sudo systemctl status mysql

# Start MySQL if not running
sudo systemctl start mysql

Create Databases

Run the initialization script to create all required databases:

-- Create all microservice databases
CREATE DATABASE IF NOT EXISTS jeaauth CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS jeacatalogo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS jeacliente CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS jesinventario CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS jeaventa CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS jeacompra CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS jeapagos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS jeaproveedor CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

FLUSH PRIVILEGES;

Execute this script:

mysql -u root -p < sql-scripts/01-init-databases.sql

Configure Database Credentials

Update database credentials in each service’s configuration file if your MySQL password is not empty.The configuration files are located in config-data/ directory:

jea-auth-service.yml
jea-catalogo-service.yml
jea-cliente-service.yml
And so on…

Example configuration:

spring:
  datasource:
    driverClassName: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/auth-jea
    username: root
    password: your_password_here

The system uses JPA with hibernate.ddl-auto: update which will automatically create tables. Ensure your MySQL user has appropriate permissions.

Infrastructure Services Setup

Start the infrastructure services in the following order:

Start Config Server

The Config Server must start first as other services depend on it for configuration.

cd jea-config-server
mvn clean install
mvn spring-boot:run

The Config Server will start on port 7070 and connect to the Git repository for configuration files:

server:
  port: 7070
spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/Erick-Franco/Sistema-ventas-ms.git
          searchPaths: config-data
          default-label: main

Verify: Access http://localhost:7070/jea-auth-service/default to check config server is working.

Start Registry Server

The Eureka Registry Server enables service discovery.

cd jea-registry-server
mvn clean install
mvn spring-boot:run

The Registry Server will start on port 8090.Verify: Access http://localhost:8090 to see the Eureka dashboard (no services registered yet).

Start Gateway Server

The API Gateway provides a single entry point for all services.

cd jea-gateway-server
mvn clean install
mvn spring-boot:run

The Gateway will start on port 8085 and register with Eureka.The gateway is configured with CORS to accept requests from the Angular frontend:

spring:
  cloud:
    gateway:
      globalcors:
        corsConfigurations:
          '[/**]':
            allowedOrigins: "http://localhost:4200"
            allowedHeaders: "*"
            allowedMethods:
              - GET
              - POST
              - PUT
              - DELETE

Startup Time: Wait 30-60 seconds after starting the Registry Server before starting other services to ensure proper registration.

Microservices Setup

Now start the business logic microservices. You can start them in any order, but the recommended sequence is:

Authentication Service

cd jea-auth
mvn clean install
mvn spring-boot:run

The service will start on a random port (configured as ${PORT:${SERVERS_PORT:0}}).This service provides:

/auth/login - User authentication
/auth/validate - Token validation (used by gateway)
/auth/create - User creation
/usuario/** - User management
/rol/** - Role management

Catalog Service

cd jea-catalogo
mvn clean install
mvn spring-boot:run

Endpoints:

/categoria/** - Category management
/producto/** - Product management
/imagenes/** - Product images (public access)

Customer Service

cd jea-cliente
mvn clean install
mvn spring-boot:run

Endpoints:

/cliente/** - Customer CRUD operations

Payment Service

cd jea-pagos
mvn clean install
mvn spring-boot:run

Endpoints:

/pagos/** - Payment methods configuration

Supplier Service

cd jea-proveedor
mvn clean install
mvn spring-boot:run

Endpoints:

/proveedor/** - Supplier management

Sales Service

cd jea-venta
mvn clean install
mvn spring-boot:run

Endpoints:

/venta/** - Sales transaction processing

Features automatic calculation of:

Base imponible (taxable amount)
IGV (18% VAT)
Total amount

Purchase Service

cd jea-compra
mvn clean install
mvn spring-boot:run

Endpoints:

/compra/** - Purchase order processing

Uses Feign clients to communicate with:

Catalog Service (products)
Supplier Service (suppliers)
Payment Service (payment methods)

Order Service

cd jea-pedidos
mvn clean install
mvn spring-boot:run

Endpoints:

/pedido/** - Customer order management

Parallel Startup: You can start multiple services in parallel by opening multiple terminal windows. Just ensure Config Server and Registry Server are running first.

Frontend Setup

Install Dependencies

Navigate to the Angular frontend directory and install npm packages:

cd sistema-ventas-frontend
npm install

This will install Angular 18.2 and all required dependencies including:

Angular Material for UI components
Chart.js for data visualization
jsPDF for report generation

Configure API Endpoint

Verify the environment configuration points to your gateway:

// src/environments/environment.development.ts
export const environment = {
  HOST: 'http://localhost:8085'  // API Gateway URL
};

Start Development Server

Run the Angular development server:

npm start
# or
ng serve

The application will be available at http://localhost:4200

Verify Installation

Check Service Registration

Open the Eureka dashboard at http://localhost:8090You should see all 8 microservices registered:

JEA-AUTH-SERVICE
JEA-CATALOGO-SERVICE
JEA-CLIENTE-SERVICE
JEA-COMPRA-SERVICE
JEA-PAGOS-SERVICE
JEA-PEDIDO-SERVICE
JEA-PROVEEDOR-SERVICE
JEA-VENTA-SERVICE

Test Authentication

Test the authentication endpoint through the gateway:

curl -X POST http://localhost:8085/auth/create \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "admin",
    "password": "admin123"
  }'

Then login:

curl -X POST http://localhost:8085/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "admin",
    "password": "admin123"
  }'

You should receive a JWT token in the response.

Test Protected Endpoint

Use the JWT token to access a protected endpoint:

curl http://localhost:8085/categoria \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

This should return the list of categories (initially empty).

Access Frontend

Open http://localhost:4200 in your browser.You should see the Sistema de Ventas login page.

Common Issues and Solutions

Port Already in Use

If you see “Port already in use” errors:

# Find process using the port (example for port 8085)
lsof -i :8085

# Kill the process
kill -9 PID

Or change the port in the service’s application.yml file.

Service Not Registering with Eureka

Common causes:

Registry Server not running
Incorrect eureka.client.serviceUrl.defaultZone configuration
Network/firewall issues

Check the service logs for connection errors. Wait 30-60 seconds for initial registration.

Database Connection Errors

Verify:

MySQL is running: sudo systemctl status mysql
Database exists: SHOW DATABASES;
Credentials are correct in configuration files
MySQL user has proper permissions

GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost';
FLUSH PRIVILEGES;

Gateway Returns 401 Unauthorized

This means JWT authentication is failing:

Ensure you’re sending the token in the Authorization header
Format: Bearer YOUR_TOKEN_HERE
Token may have expired (1 hour lifetime)
Auth service must be running for token validation

CORS Errors in Browser

If you see CORS errors in the browser console:

Verify Gateway CORS configuration allows http://localhost:4200
Check that you’re accessing the API through the gateway (port 8085)
Don’t access services directly from the browser

Development Workflow

Make Code Changes

Edit your service code using your preferred IDE (IntelliJ IDEA, VS Code, Eclipse).

Rebuild Service

cd service-directory
mvn clean install

Restart Service

Stop the running service (Ctrl+C) and start it again:

mvn spring-boot:run

Or use Spring Boot DevTools for automatic restart on code changes.

Test Changes

Use the frontend application or API testing tools like Postman to verify your changes.

Production Deployment

The quickstart configuration is for development only. For production deployment:

Change JWT secret from default "secret"
Use strong database passwords
Configure SSL/TLS for all services
Use external configuration management
Set up proper monitoring and logging
Configure container orchestration (Kubernetes, Docker Swarm)
Implement API rate limiting
Set up database replication and backups

Next Steps

Explore Features

Learn about each service’s capabilities in detail

API Documentation

Explore available endpoints and request/response formats

Architecture Deep Dive

Understand the system design patterns

Security Guide

Learn about authentication, authorization, and best practices

Getting Help

If you encounter issues:

Check service logs for error messages
Verify all prerequisites are installed correctly
Ensure services start in the correct order
Review the Eureka dashboard for service health
Test each component individually before testing the full system

Pro Tip: Use a process manager like tmux or separate terminal tabs to manage multiple services simultaneously. Consider using Docker Compose for easier multi-service management.

Get Started

Core Features

Deployment

Prerequisites

Java Development Kit

MySQL Database

Maven Build Tool

Node.js & npm

Database Setup

Infrastructure Services Setup

Microservices Setup

Frontend Setup

Verify Installation

Common Issues and Solutions

Development Workflow

Production Deployment

Next Steps

Explore Features

API Documentation

Architecture Deep Dive

Security Guide

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Features

Deployment

​Prerequisites

Java Development Kit

MySQL Database

Maven Build Tool

Node.js & npm

​Database Setup

​Infrastructure Services Setup

​Microservices Setup

​Frontend Setup

​Verify Installation

​Common Issues and Solutions

​Development Workflow

​Production Deployment

​Next Steps

Explore Features

API Documentation

Architecture Deep Dive

Security Guide

​Getting Help

Build docs developers (and LLMs) love

Prerequisites

Database Setup

Infrastructure Services Setup

Microservices Setup

Frontend Setup

Verify Installation

Common Issues and Solutions

Development Workflow

Production Deployment

Next Steps

Getting Help