Version: 1.0
Fecha: 16 de Marzo, 2026
Estado: NORMATIVO - Procedimiento Obligatorio
Arquitecto: Carlos Alberto Torres Camargo
Servicio de referencia: nebula-accounting-core
Para ejecutar un microservicio Nebula en entorno local se requiere:
~/.m2/)Antes de iniciar, verificar que se tiene instalado:
| Software | Version Minima | Verificar con |
|---|---|---|
| JDK | 25 | java -version |
| Maven | 3.9+ | mvn -version |
| Docker + Docker Compose | Latest | docker --version |
| Git | Latest | git --version |
| IDE | IntelliJ IDEA o Eclipse | Con plugin Lombok |
| VPN Centrica | Conectada | Acceso a Nexus |
Configuracion detallada: Setup Ambiente de Desarrollo
Maven settings.xml: Configuracion Nexus y Maven
Las bases de datos y servicios de mensajeria se levantan con Docker Compose o de forma individual.
docker run -d \
--name nebula-postgres \
-e POSTGRES_DB=simappe_admin \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-p 5432:5432 \
postgres:16
docker run -d \
--name nebula-mongo \
-p 27017:27017 \
mongo:7.0
docker run -d \
--name nebula-redis \
-p 6379:6379 \
redis:7-alpine
# Zookeeper
docker run -d \
--name nebula-zookeeper \
-e ZOOKEEPER_CLIENT_PORT=2181 \
-p 2181:2181 \
confluentinc/cp-zookeeper:7.5.0
# Kafka
docker run -d \
--name nebula-kafka \
-e KAFKA_ZOOKEEPER_CONNECT=host.docker.internal:2181 \
-e KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092 \
-e KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1 \
-p 9092:9092 \
confluentinc/cp-kafka:7.5.0
# PostgreSQL
docker exec nebula-postgres pg_isready
# Esperado: /var/run/postgresql:5432 - accepting connections
# MongoDB
docker exec nebula-mongo mongosh --eval "db.runCommand({ping:1})"
# Esperado: { ok: 1 }
# Redis
docker exec nebula-redis redis-cli ping
# Esperado: PONG
# Kafka
docker exec nebula-kafka kafka-broker-api-versions --bootstrap-server localhost:9092 | head -1
# Esperado: ApiVersion(...) (sin error)
El orden es estricto debido a las dependencias entre librerias. Si se instala en orden incorrecto, Maven fallara con errores de dependencias no resueltas.
Ejecutar desde el directorio de cada proyecto, en el orden indicado:
# ──────────────────────────────────────────────
# CAPA 1: SIMAPPE (Infraestructura)
# ──────────────────────────────────────────────
# 1. SimappeModel (sin dependencias — se instala primero)
cd /ruta/al/workspace/backend/SimappeModel
./mvnw clean install -DskipTests
# Resultado: SimappeModel-3.1.0.jar instalado en ~/.m2/
# 2. SimappeCommons (depende de SimappeModel)
cd /ruta/al/workspace/backend/simappecommons
./mvnw clean install -DskipTests
# Resultado: SimappeCommons-2.8.4.jar instalado en ~/.m2/
# ──────────────────────────────────────────────
# CAPA 2: NEBULA (Negocio)
# ──────────────────────────────────────────────
# 3. nebula-models (depende de SimappeModel)
cd /ruta/al/workspace/backend/nebula-models
./mvnw clean install -DskipTests
# Resultado: nebula-models-0.0.2-SNAPSHOT.jar instalado en ~/.m2/
# 4. nebula-commons (depende de nebula-models)
cd /ruta/al/workspace/backend/nebula-commons
./mvnw clean install -DskipTests
# Resultado: nebula-commons-0.0.1-SNAPSHOT.jar instalado en ~/.m2/
# 5. nebula-shared (depende de nebula-models)
cd /ruta/al/workspace/backend/nebula-shared
./mvnw clean install -DskipTests
# Resultado: nebula-shared-0.0.1-SNAPSHOT.jar instalado en ~/.m2/
Nota: Se usa
-DskipTestspara acelerar la instalacion. Las librerias ya fueron testeadas antes de publicarse.
# Verificar que los artefactos existen en el repositorio local
ls ~/.m2/repository/com/catcsoft/simappe/SimappeModel/3.1.0/
ls ~/.m2/repository/com/catcsoft/simappe/SimappeCommons/2.8.4/
ls ~/.m2/repository/com/centrica/nebula/nebula-models/0.0.2-SNAPSHOT/
ls ~/.m2/repository/com/centrica/nebula/nebula-commons/0.0.1-SNAPSHOT/
ls ~/.m2/repository/com/centrica/nebula/nebula-shared/0.0.1-SNAPSHOT/
Para automatizar, se puede crear un script:
#!/bin/bash
# install-all-libs.sh
# Instala todas las librerias Simappe/Nebula en orden
set -e # Detener al primer error
WORKSPACE="/ruta/al/workspace/backend"
echo "=== Instalando SimappeModel ==="
cd "$WORKSPACE/SimappeModel" && ./mvnw clean install -DskipTests
echo "=== Instalando SimappeCommons ==="
cd "$WORKSPACE/simappecommons" && ./mvnw clean install -DskipTests
echo "=== Instalando nebula-models ==="
cd "$WORKSPACE/nebula-models" && ./mvnw clean install -DskipTests
echo "=== Instalando nebula-commons ==="
cd "$WORKSPACE/nebula-commons" && ./mvnw clean install -DskipTests
echo "=== Instalando nebula-shared ==="
cd "$WORKSPACE/nebula-shared" && ./mvnw clean install -DskipTests
echo "=== Todas las librerias instaladas correctamente ==="
Los servicios de plataforma Simappe deben arrancarse en orden estricto, ya que tienen dependencias entre si.
Cada servicio se arranca en una terminal independiente con el perfil localhost:
# ──────────────────────────────────────────────
# TERMINAL 1: Eureka Server (Service Discovery)
# ──────────────────────────────────────────────
cd /ruta/al/workspace/backend/simappeeurekaserver
./mvnw spring-boot:run -Dspring-boot.run.profiles=localhost
# Esperar hasta ver: "Started SimappeEurekaServerApplication"
# Dashboard: http://localhost:8761
# ──────────────────────────────────────────────
# TERMINAL 2: Config Server (Configuracion Centralizada)
# ──────────────────────────────────────────────
cd /ruta/al/workspace/backend/simappeconfigserver
./mvnw spring-boot:run -Dspring-boot.run.profiles=localhost
# Esperar hasta ver: "Started SimappeConfigServerApplication"
# Verificar: http://localhost:8890/actuator/health
# ──────────────────────────────────────────────
# TERMINAL 3: Gateway Server (API Gateway)
# ──────────────────────────────────────────────
cd /ruta/al/workspace/backend/simappegatewayserver
./mvnw spring-boot:run -Dspring-boot.run.profiles=localhost
# Esperar hasta ver: "Started SimappeGatewayServerApplication"
# Puerto: 8090
# ──────────────────────────────────────────────
# TERMINAL 4: OAuth2 Server (Autenticacion)
# ──────────────────────────────────────────────
cd /ruta/al/workspace/backend/simappeoauth2server
./mvnw spring-boot:run -Dspring-boot.run.profiles=localhost
# Esperar hasta ver: "Started SimappeOauth2ServerApplication"
# Puerto: 8787
# ──────────────────────────────────────────────
# TERMINAL 5: Admin (Centro de Control)
# ──────────────────────────────────────────────
cd /ruta/al/workspace/backend/simappeadmin
./mvnw spring-boot:run -Dspring-boot.run.profiles=localhost
# Esperar hasta ver: "Started SimappeAdminApplication"
# Puerto: 9010
# ──────────────────────────────────────────────
# TERMINAL 6: Client
# ──────────────────────────────────────────────
cd /ruta/al/workspace/backend/simappeclient
./mvnw spring-boot:run -Dspring-boot.run.profiles=localhost
# Esperar hasta ver: "Started SimappeClientApplication"
# Puerto: 9020
Importante: Esperar a que cada servicio termine de arrancar completamente antes de iniciar el siguiente. Verificar en el log que aparece el mensaje "Started...Application".
# 1. Eureka Dashboard — ver todos los servicios registrados
# Abrir en navegador: http://localhost:8761
# 2. Health check de cada servicio
curl -s http://localhost:8761/actuator/health | jq .status # Eureka
curl -s http://localhost:8890/actuator/health | jq .status # Config
curl -s http://localhost:8090/actuator/health | jq .status # Gateway
curl -s http://localhost:8787/simappe-oauth2-server/actuator/health | jq .status # OAuth2
curl -s http://localhost:9010/simappe-admin/actuator/health | jq .status # Admin
curl -s http://localhost:9020/simappe-client/actuator/health | jq .status # Client
# Esperado para todos: "UP"
Con toda la infraestructura y servicios de plataforma arrancados:
# ──────────────────────────────────────────────
# TERMINAL 7: nebula-accounting-core
# ──────────────────────────────────────────────
cd /ruta/al/workspace/backend/nebula-accounting-core
./mvnw spring-boot:run -Dspring-boot.run.profiles=localhost
# Health check
curl -s http://localhost:8181/nebula-accounting-core/actuator/health | jq .
# Disponibilidad del servicio (endpoint index)
curl -s http://localhost:8181/nebula-accounting-core/api/v1/centro-costos/
# Swagger UI
# Abrir en navegador: http://localhost:8181/nebula-accounting-core/swagger-ui.html
# Verificar registro en Eureka
# Abrir: http://localhost:8761 — debe aparecer NEBULA-ACCOUNTING-CORE
PASO 1: Docker (PostgreSQL, MongoDB, Redis, Kafka)
│
▼
PASO 2: mvn install (SimappeModel → SimappeCommons → nebula-models → nebula-commons → nebula-shared)
│
▼
PASO 3: Servicios (Eureka → Config → Gateway → OAuth2 → Admin → Client)
│
▼
PASO 4: Microservicio (nebula-accounting-core con perfil localhost)
│
▼
VERIFICAR: Eureka Dashboard + Health Checks + Swagger UI
Could not find artifact com.catcsoft.simappe:SimappeCommons:jar:2.8.4
Causa: La libreria no esta instalada en ~/.m2/ ni disponible en Nexus.
Solucion: Ejecutar mvn clean install -DskipTests en el proyecto de la libreria. Verificar orden de instalacion.
Could not resolve placeholder 'database.template.sql.url'
Causa: Config Server no esta arrancado o el perfil no existe en el repositorio de configuraciones.
Solucion: Verificar que Config Server esta en http://localhost:8890/actuator/health = UP. Si se trabaja sin Config Server, usar perfil localhost que tiene configuraciones locales.
com.netflix.discovery.shared.transport.TransportException: Cannot execute request on any known server
Causa: Eureka Server no esta arrancado.
Solucion: Arrancar Eureka Server primero. Verificar en http://localhost:8761.
com.mongodb.MongoSocketOpenException: Exception opening socket
Causa: MongoDB no esta corriendo.
Solucion: Verificar docker ps | grep mongo. Reiniciar si es necesario: docker start nebula-mongo.
Web server failed to start. Port XXXX was already in use.
Causa: Otro proceso usa el mismo puerto.
Solucion: lsof -i :XXXX para identificar el proceso. kill -9 PID para liberarlo.
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.0.0 | 2026-03-16 | Carlos Torres | Creacion del documento |