Skip to main content

Configuración del Entorno de Desarrollo

Esta guía te ayudará a configurar un entorno de desarrollo completo para ClickAware en tu máquina local.

Requisitos del Sistema​

Software Necesario​

  • Node.js: v18.0+ (recomendado v20.0+)
  • Java: JDK 21+ (Oracle JDK o OpenJDK)
  • Maven: v3.8+
  • PostgreSQL: v14+
  • Git: v2.30+

Herramientas Recomendadas​

  • IDE: IntelliJ IDEA (Ultimate) o VS Code
  • Terminal: Git Bash (Windows) o Terminal nativo (macOS/Linux)
  • Cliente de Base de Datos: pgAdmin 4 o DBeaver
  • Cliente API: Postman o Insomnia

Clonar el Repositorio​

# Clonar el repositorio principal
git clone https://github.com/clickaware/clickaware-monolith.git
cd clickaware-monolith

# Inicializar submódulos (si los hay)
git submodule update --init --recursive

Configuración de Base de Datos​

1. Instalar PostgreSQL​

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib

# macOS (usando Homebrew)
brew install postgresql
brew services start postgresql

# Windows
# Descargar e instalar desde https://www.postgresql.org/download/windows/

2. Crear Base de Datos​

-- Conectar como superusuario
sudo -u postgres psql

-- Crear base de datos y usuario
CREATE DATABASE clickaware_dev;
CREATE USER clickaware_user WITH PASSWORD 'clickaware_pass';
GRANT ALL PRIVILEGES ON DATABASE clickaware_dev TO clickaware_user;

-- Salir
\q

3. Configurar Variables de Entorno​

Crear archivo .env en la raíz del proyecto:

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=clickaware_dev
DB_USER=clickaware_user
DB_PASSWORD=clickaware_pass

# JWT Configuration
JWT_SECRET=tu_jwt_secret_muy_seguro_aqui
JWT_EXPIRATION=86400000

# Email Configuration (para desarrollo)
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=tu_email@gmail.com
MAIL_PASSWORD=tu_app_password

# Application URLs
FRONTEND_URL=http://localhost:4200
ADMIN_URL=http://localhost:4202
DOCS_URL=http://localhost:3000

Configuración del Backend​

1. Navegar al Directorio Backend​

cd backend

2. Configurar application.yml​

Editar src/main/resources/application.yml:

spring:
profiles:
active: dev

datasource:
url: jdbc:postgresql://localhost:5432/clickaware_dev
username: clickaware_user
password: clickaware_pass
driver-class-name: org.postgresql.Driver

jpa:
hibernate:
ddl-auto: update
show-sql: true
properties:
hibernate:
dialect: org.hibernate.dialect.PostgreSQLDialect
format_sql: true

mail:
host: ${MAIL_HOST}
port: ${MAIL_PORT}
username: ${MAIL_USERNAME}
password: ${MAIL_PASSWORD}
properties:
mail:
smtp:
auth: true
starttls:
enable: true

server:
port: 8086

jwt:
secret: ${JWT_SECRET}
expiration: ${JWT_EXPIRATION}

logging:
level:
com.politeia.clickaware: DEBUG
org.springframework.security: DEBUG

3. Instalar Dependencias y Ejecutar​

# Instalar dependencias
mvn clean install -DskipTests

# Ejecutar aplicación
mvn spring-boot:run

# O en modo desarrollo con recarga automática
mvn spring-boot:run -Dspring-boot.run.profiles=dev

La aplicación backend estará disponible en: http://localhost:8086

Configuración del Frontend Principal​

1. Navegar al Directorio Frontend​

cd SCFront

2. Instalar Dependencias​

# Usando npm
npm install

# O usando yarn
yarn install

3. Configurar Variables de Entorno​

Crear archivo src/environment/environment.ts:

export const environment = {
production: false,
name: 'local',
BASE_URL: 'localhost:8086',
ANGULAR_PORT: ':4200',
PROTOCOLO: 'http',
COMENTARIOS: 'false',
POLITEIA: 'https://gateway.politeiasoft.com/',
shopUrl: 'http://localhost:4201'
};

4. Ejecutar Aplicación​

# Modo desarrollo
npm start
# o
ng serve

# Con puerto específico
ng serve --port 4200

La aplicación frontend estará disponible en: http://localhost:4200

Configuración del Panel de Administración​

1. Navegar al Directorio Admin​

cd admin

2. Instalar y Ejecutar​

# Instalar dependencias
npm install

# Ejecutar en modo desarrollo
npm start
# o
ng serve --port 4202

El panel de administración estará disponible en: http://localhost:4202

Configuración de la Documentación​

1. Navegar al Directorio Docs​

cd docs

2. Instalar y Ejecutar​

# Instalar dependencias
npm install

# Ejecutar en modo desarrollo
npm start

La documentación estará disponible en: http://localhost:3000

Verificación de la Instalación​

1. Verificar Backend​

curl http://localhost:8086/api/health

Respuesta esperada:

{
"status": "UP",
"timestamp": "2025-01-01T10:00:00.000Z"
}

2. Verificar Frontend​

Abrir http://localhost:4200 y verificar que carga la página de login.

3. Verificar Admin Panel​

Abrir http://localhost:4202 y verificar que carga la página de administración.

4. Verificar Documentación​

Abrir http://localhost:3000 y verificar que carga Docusaurus.

Scripts de Desarrollo Útiles​

Backend​

# Ejecutar tests
mvn test

# Ejecutar con profile específico
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# Generar JAR
mvn clean package -DskipTests

# Ejecutar con debug
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"

Frontend​

# Ejecutar con recarga automática
ng serve --watch

# Ejecutar tests
ng test

# Ejecutar e2e tests
ng e2e

# Build para producción
ng build --configuration production

Base de Datos​

# Resetear base de datos (CUIDADO: borra todos los datos)
psql -U clickaware_user -d clickaware_dev -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"

# Backup de base de datos
pg_dump -U clickaware_user clickaware_dev > backup.sql

# Restaurar backup
psql -U clickaware_user clickaware_dev < backup.sql

Problemas Comunes​

Error de Conexión a Base de Datos​

org.postgresql.util.PSQLException: Connection refused

Solución:

  1. Verificar que PostgreSQL esté ejecutándose
  2. Verificar credenciales en application.yml
  3. Verificar que el puerto 5432 esté disponible

Error de CORS en Frontend​

Access to XMLHttpRequest blocked by CORS policy

Solución: Verificar configuración de CORS en SecurityConfig.java:

@Bean
public CorsConfigurationSource corsConfigurationSource() {
CorsConfiguration configuration = new CorsConfiguration();
configuration.setAllowedOriginPatterns(Arrays.asList("*"));
configuration.setAllowedMethods(Arrays.asList("*"));
configuration.setAllowedHeaders(Arrays.asList("*"));
configuration.setAllowCredentials(true);
// ...
}

Puerto Ya en Uso​

Web server failed to start. Port 8086 was already in use

Solución:

# Encontrar proceso usando el puerto
lsof -i :8086

# Matar proceso
kill -9 <PID>

# O cambiar puerto en application.yml
server.port: 8087

Próximos Pasos​

Una vez que tengas el entorno configurado:

  1. Explorar la API: Usar Postman con la colección de ClickAware
  2. Revisar la base de datos: Familiarizarse con el esquema
  3. Ejecutar tests: Asegurarse de que todo funciona correctamente
  4. Contribuir: Consultar API Reference

¿Problemas durante la configuración? Consulta: