Backend Setup

This guide covers the complete setup process for all backend microservices in Sistema de Ventas.

Service Architecture Overview

Sistema de Ventas follows a microservices architecture with:

2 Infrastructure Services: Config Server, Eureka Registry
1 API Gateway: Spring Cloud Gateway
8 Business Services: Auth, Catalogo, Cliente, Venta, Compra, Pedidos, Pagos, Proveedor

Service Dependencies

Spring Boot Version Matrix

Service	Spring Boot	Spring Cloud	Java	Database
Config Server	3.5.0	2025.0.0-RC1	17	-
Registry Server	3.5.0	2025.0.0-RC1	17	-
Gateway Server	3.3.3	2023.0.3	17	-
Auth Service	2.5.4	2020.0.3	17	MySQL
Cliente Service	3.1.3	2022.0.2	17	PostgreSQL
Catalogo Service	3.1.3	2022.0.2	17	MySQL
Venta Service	3.1.3	2022.0.2	17	MySQL
Compra Service	3.1.3	2022.0.2	17	MySQL
Pedidos Service	3.1.3	2022.0.2	17	MySQL
Pagos Service	3.1.3	2022.0.2	17	MySQL
Proveedor Service	3.1.3	2022.0.2	17	MySQL

Prerequisites

Before starting, ensure:

Prerequisites installed
Databases configured
Ports available: 7070, 8085, 8090

Clone Repository

git clone https://github.com/Erick-Franco/Sistema-ventas-ms.git
cd Sistema-ventas-ms

Infrastructure Services

Step 1: Start Config Server

The Config Server must start first as it provides configuration to all other services.

Navigate to Config Server

cd jea-config-server

Review Configuration

The Config Server is configured to read from GitHub:

config-server/src/main/resources/application.yml

server:
  port: 7070
spring:
  application:
    name: config-server
  cloud:
    config:
      server:
        git:
          uri: https://github.com/Erick-Franco/Sistema-ventas-ms.git
          searchPaths: config-data
          default-label: main
  security:
    user:
      name: root
      password: 123456

Build and Run

# Clean and install
mvn clean install -DskipTests

# Run the service
mvn spring-boot:run

Verify Config Server

# Check health
curl http://localhost:7070/actuator/health

# Test configuration endpoint
curl http://root:123456@localhost:7070/jea-auth-service/default

Expected: Configuration JSON response

Keep this terminal open. Config Server must run continuously.

Step 2: Start Eureka Registry Server

Navigate to Registry Server

Open a new terminal:

cd jea-registry-server

Review Configuration

registry-server/config-data/jea-registry-service.yml

server:
  port: 8090
eureka:
  instance:
    hostname: localhost
  client:
    registerWithEureka: false
    fetchRegistry: false
    serviceUrl:
      defaultZone: http://localhost:8090/eureka/

Build and Run

mvn clean install -DskipTests
mvn spring-boot:run

Verify Registry Server

Open browser: http://localhost:8090You should see the Eureka Dashboard.

Keep this terminal open. All microservices register with Eureka.

Step 3: Start API Gateway

Navigate to Gateway

Open a new terminal:

cd jea-gateway-server

Review Gateway Configuration

The gateway routes all requests to microservices:

config-data/jea-gateway-service.yml

server:
  port: 8085

spring:
  cloud:
    gateway:
      globalcors:
        corsConfigurations:
          '[/**]':
            allowedOrigins: "http://localhost:4200"
            allowedHeaders: "*"
            allowedMethods:
              - GET
              - POST
              - PUT
              - DELETE
      routes:
        - id: jea-auth-service
          uri: lb://jea-auth-service
          predicates:
            - Path=/auth/**, /usuario/**, /rol/**
        
        - id: jea-catalogo-service
          uri: lb://jea-catalogo-service
          predicates:
            - Path=/categoria/**, /producto/**, /imagenes/**
          filters:
            - AuthFilter

Build and Run

mvn clean install -DskipTests
mvn spring-boot:run

Verify Gateway

# Check gateway health
curl http://localhost:8085/actuator/health

Check Eureka Dashboard - Gateway should be registered.

Business Microservices

Step 4: Start Auth Service

The Auth service handles user authentication and JWT token generation.

Navigate to Auth Service

Open a new terminal:

cd jea-auth

Review Auth Configuration

config-data/jea-auth-service.yml

server:
  port: ${PORT:${SERVERS_PORT:0}}  # Dynamic port

spring:
  application:
    name: jea-auth-service
  datasource:
    url: jdbc:mysql://localhost:3306/auth-jea
    username: root
    password: ""
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true

jwt:
  secret: secret

Update Dependencies

mvn clean install -DskipTests

Run Auth Service

mvn spring-boot:run

The service will:

Connect to Config Server
Register with Eureka
Create database tables automatically
Start on a dynamic port

Verify Auth Service

Check Eureka Dashboard at http://localhost:8090jea-auth-service should appear in registered instances.

Step 5: Start Remaining Business Services

Start each service in a new terminal:

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

Configuration:

Database: catalogo-ms (MySQL)
Dynamic port allocation
Swagger UI: /doc/swagger-ui.html

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

Configuration:

Database: cliente-jea (PostgreSQL)
Port: Dynamic
Swagger UI enabled

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

Configuration:

Database: venta-jea (MySQL)
Circuit Breaker: Resilience4j
Feign Clients for inter-service communication

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

Configuration:

Database: compra-jea (MySQL)
Circuit Breaker enabled

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

Configuration:

Database: pedido-jea (MySQL)
Dynamic port

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

Configuration:

Database: pagos-jea (MySQL)
Manages payment methods

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

Configuration:

Database: proveedor-jea (MySQL)
Supplier management

Startup Order Summary

CRITICAL: Services must start in this order:

Infrastructure Layer

Config Server (port 7070) - Wait 30 seconds
Eureka Registry (port 8090) - Wait 30 seconds
API Gateway (port 8085) - Wait 20 seconds

Business Layer

Auth Service - Wait for Eureka registration
All other services (can start in parallel)

Verify Complete Deployment

Check Eureka Dashboard

Visit: http://localhost:8090 You should see all services registered:

Expected Registered Services

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

Test Gateway Routes

# Gateway health
curl http://localhost:8085/actuator/health

Service Configuration Details

Database Connections

# Auth, Catalogo, Venta, Compra, Pedidos, Pagos, Proveedor
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/<database-name>
    username: root
    password: ""
    driver-class-name: com.mysql.cj.jdbc.Driver

Eureka Client Configuration

All services connect to Eureka:

eureka:
  client:
    serviceUrl:
      defaultZone: http://localhost:8090/eureka
  instance:
    hostname: localhost
    instance-id: ${spring.application.name}:${spring.application.instance_id:${random.value}}

Circuit Breaker Configuration

Venta, Compra, and Pedidos services use Resilience4j:

resilience4j.circuitbreaker:
  instances:
    orderByIdCB:
      registerHealthIndicator: true
      slidingWindowSize: 10
      permittedNumberOfCallsInHalfOpenState: 3
      slidingWindowType: TIME_BASED
      minimumNumberOfCalls: 4
      waitDurationInOpenState: 5s
      failureRateThreshold: 50
      eventConsumerBufferSize: 10

Troubleshooting

Service won't start - Config Server connection failed

Issue: Could not locate PropertySource errorSolutions:

Ensure Config Server is running on port 7070

Check bootstrap.yml has correct config server URL:

spring:
  cloud:
    config:
      uri: http://localhost:7070

Verify config-data folder exists in GitHub repo

Service not registering with Eureka

Issue: Service doesn’t appear in Eureka dashboardSolutions:

Check Eureka is running: http://localhost:8090
Verify application.yml has eureka client config
Check logs for connection errors
Wait 30-60 seconds for registration

Database connection failed

Issue: Communications link failure or Access deniedSolutions:

Verify database exists: SHOW DATABASES;
Check username/password in service config
Ensure MySQL/PostgreSQL is running
Test connection: mysql -u root -p

Port already in use

Issue: Port 8085 is already in useSolutions:

# Find process using port
lsof -i :8085

# Kill process
kill -9 <PID>

# Or use different port
mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=8086

Maven build fails

Issue: Dependencies not resolvingSolutions:

# Clear Maven cache
mvn dependency:purge-local-repository

# Force update
mvn clean install -U

# Skip tests
mvn clean install -DskipTests

Production Deployment

Build Production JARs

Build All Services

# Build all services
for dir in jea-*/; do
  echo "Building $dir"
  cd "$dir"
  mvn clean package -DskipTests
  cd ..
done

Create Deployment Directory

mkdir -p deployment/jars

# Copy all JARs
find . -name "*.jar" -path "*/target/*" -exec cp {} deployment/jars/ \;

Run with Production Profiles

# Config Server
java -jar -Dspring.profiles.active=prod jea-config-server-0.0.1-SNAPSHOT.jar

# Eureka Registry
java -jar -Dspring.profiles.active=prod jea-registry-server-0.0.1-SNAPSHOT.jar

# Gateway
java -jar -Dspring.profiles.active=prod jea-gateway-server-0.0.1-SNAPSHOT.jar

Environment Variables

Use environment variables for production:

export SPRING_PROFILES_ACTIVE=prod
export CONFIG_SERVER_URI=http://config-server:7070
export EUREKA_URI=http://eureka-server:8090/eureka
export DB_HOST=mysql-server
export DB_PASSWORD=secure_password

java -jar jea-auth-0.0.1-SNAPSHOT.jar

Automated Startup Script

Create start-all.sh:

start-all.sh

#!/bin/bash

echo "Starting Config Server..."
cd jea-config-server && mvn spring-boot:run &
sleep 30

echo "Starting Eureka Registry..."
cd ../jea-registry-server && mvn spring-boot:run &
sleep 30

echo "Starting API Gateway..."
cd ../jea-gateway-server && mvn spring-boot:run &
sleep 20

echo "Starting Auth Service..."
cd ../jea-auth && mvn spring-boot:run &
sleep 10

echo "Starting Business Services..."
cd ../jea-catalogo && mvn spring-boot:run &
cd ../jea-cliente && mvn spring-boot:run &
cd ../jea-venta && mvn spring-boot:run &
cd ../jea-compra && mvn spring-boot:run &
cd ../jea-pedidos && mvn spring-boot:run &
cd ../jea-pagos && mvn spring-boot:run &
cd ../jea-proveedor && mvn spring-boot:run &

echo "All services started! Check Eureka: http://localhost:8090"

chmod +x start-all.sh
./start-all.sh

Get Started

Core Features

Deployment

Service Architecture Overview

Service Dependencies

Spring Boot Version Matrix

Prerequisites

Clone Repository

Infrastructure Services

Step 1: Start Config Server

Step 2: Start Eureka Registry Server

Step 3: Start API Gateway

Business Microservices

Step 4: Start Auth Service

Step 5: Start Remaining Business Services

Startup Order Summary

Verify Complete Deployment

Check Eureka Dashboard

Test Gateway Routes

Service Configuration Details

Database Connections

Eureka Client Configuration

Circuit Breaker Configuration

Troubleshooting

Production Deployment

Build Production JARs

Environment Variables

Automated Startup Script

Next Steps

Frontend Setup

Docker Deployment

Build docs developers (and LLMs) love

Get Started

Core Features

Deployment

​Service Architecture Overview

​Service Dependencies

​Spring Boot Version Matrix

​Prerequisites

​Clone Repository

​Infrastructure Services

​Step 1: Start Config Server

​Step 2: Start Eureka Registry Server

​Step 3: Start API Gateway

​Business Microservices

​Step 4: Start Auth Service

​Step 5: Start Remaining Business Services

​Startup Order Summary

​Verify Complete Deployment

​Check Eureka Dashboard

​Test Gateway Routes

​Service Configuration Details

​Database Connections

​Eureka Client Configuration

​Circuit Breaker Configuration

​Troubleshooting

​Production Deployment

​Build Production JARs

​Environment Variables

​Automated Startup Script

​Next Steps

Frontend Setup

Docker Deployment

Build docs developers (and LLMs) love

Service Architecture Overview

Service Dependencies

Spring Boot Version Matrix

Prerequisites

Clone Repository

Infrastructure Services

Step 1: Start Config Server

Step 2: Start Eureka Registry Server

Step 3: Start API Gateway

Business Microservices

Step 4: Start Auth Service

Step 5: Start Remaining Business Services

Startup Order Summary

Verify Complete Deployment

Check Eureka Dashboard

Test Gateway Routes

Service Configuration Details

Database Connections

Eureka Client Configuration

Circuit Breaker Configuration

Troubleshooting

Production Deployment

Build Production JARs

Environment Variables

Automated Startup Script

Next Steps