¿Cómo compilar y ejecutar Onesait Platform con el Workspace?
- 1 Introducción
- 2 Requisitos
- 3 Paso 1: Conoce tu Workspace
- 4 Paso 2: Clonar el Repositorio y Primer Build del Proyecto
- 4.1 Cómo Clonar
- 4.2 El Primer Build
- 5 Paso 3: Configurar el IDE
- 6 Paso 4: Preparar las Bases de Datos
- 7 Paso 5: Ejecutar Control Panel de Plataforma
- 8 Paso 6: Ejecutar otros módulos de Plataforma
- 9 Problemas Conocidos
Introducción
Esta guía, describe los pasos necesarios para poder empezar a trabajar con Onesait Platform en tu local. El entorno de desarrollo dockerizado tiene como objetivos conseguir facilitar y agilizar la configuración del setup necesario para comenzar a desarrollar.
Entre otras cosas, se incluyen herramientas como:
JDK 8
JDK 17
Maven 3.8.7
Maven Daemon
Git
Todas estas herramientas tienen su versión tanto para sistemas operativos basados en Unix (Linux y MacOS) como para Windows.
Si eres un desarrollador experto puedes utilizar tus propias herramientas; entonces probablemente prefieras empezar con esta guía: (Develop) Cómo compilar y ejecutar el Panel de Control de la Plataforma de Eclipse
Requisitos
Antes de comenzar, descarga el fichero comprimido OnesaitPlatform-workspace.zip que contiene todos los ficheros necesarios para trabajar y además, debes tener instalado en tu ordenador lo siguiente:
Docker
Docker Compose
Si usas Windows o MacOs, puedes utilizar https://docs.docker.com/desktop/ o https://rancherdesktop.io/.
Paso 1: Conoce tu Workspace
Vamos a analizar la estructura de ficheros y directorios dentro de tu workspace:
Las carpetas marcadas con al final de la línea, son carpetas que no verás al principio pero una vez que inicies determinados contenedores, verás que aparecen, ya que son parte de los volumenes de dichos contenedores.
🌳 OnsaitPlatform-Workspace
📁 config – toda la configuración necesaria para el espacio de trabajo.
📁 certs – certificados necesarios para la descarga de dependencias.
📁 mariadb – configuración de mariadb (init.sql, init.cnf).
📁 maven – configuración de maven (settings.xml).
📁 dockerfiles – dockerfiles para construir las imágenes que se necesiten.
📁 scripts – ficheros de script útiles para configurar permisos necesarios y clonar el proyecto.
📁 linux – setup.sh.
📁 windows – setup.bat.
📁 m2_repo – repositorio maven.
📁 project – donde el Proyecto clonado irá ubicado.
📁 tools – diferentes herramientas del workspace.
📁 linux – git, jdk, maven.
📁 windows – git, jdk, maven.
📄 docker-compose.yaml – fichero que orquesta los servicios externos (base de datos y clientes UI) que necesita la plataforma para funcionar correctamente.
Paso 2: Clonar el Repositorio y Primer Build del Proyecto
Para usuarios de Windows, debido al tamaño del repositorio del proyecto, puede que tengas problemas para clonarlo y es recomendable utilizar WSL, con lo que deberías poder clonar sin mucho problema (Aunque puede que necesites varios intentos hasta conseguir que clone).
Cómo Clonar
Como habrás podido observar en el paso 2, tenemos una carpeta llamada scripts que contiene tanto para Windows como para Linux/MacOS unos ficheros que nos ayudarán a descargar el proyecto y a configurar unos permisos necesarios para el fichero init.cnf para que no tengamos problemas más adelante.
Lo primero, será situarte dentro de la carpeta correspondiente según tu SO, lo harás desde una terminal para poder ejecutar el script ('./setup.sh' o ‘.\setup.bat’). Si tienes algún problema al ejecutarlos, comprueba que dichos ficheros tienen permiso de ejecución.
Podrás ver el siguiente menú en la terminal, en función de tu sistema operativo:
Son dos opciones muy sencillas e intuitivas, pero la única requerida es la primera ya que puedes elegir clonar el repositorio por tu cuenta, aunque no olvides situarlo en la carpeta project (sino existe debes crearla) en la raíz de nuestro workspace.
git clone https://github.com/onesaitplatform/onesaitplatform-cloudEl Primer Build
Para hacer el primer build del proyecto, simplemente necesitas levantar un contenedor definido en el fichero docker-compose.yml como onesait-platform-env. Los pasos a seguir:
Ejecuta el comando
docker compose up onesait-platform-envy espera que el servicio inicie.Cuando veas en pantalla estos mensajes, el contendor estará listo para que accedas a él usando el comando
docker execque puedes ver en los logs.
Para obtener el container id, puedes ejecutar el comando
docker psy el primer dato que verás, es el identificador único:
Ahora, ya puedes acceder al contenedor , dónde verás que apareces situado en la ruta ‘/workspace/project’, y desde aquí simplemente navegas al directorio ‘sources’ dónde ejecutando el alias mvndcinotest, si todo va bien, comenzará el primer build.
Sé paciente, la primera vez puede demorarse algo más de 20 minutos debido a la descarga de dependencias.
Paso 3: Configurar el IDE
Para este paso, necesitarás tener instalado un IDE como Eclipse, Netbeans o IntelliJ, puedes usar el que prefieras. En mi caso, trabajaré con IntelliJ Community Edition.
Lo primero será abrir el proyecto ubicado en ‘OnesaitPlatform-Workspace/project/sources’ con nuestro IDE. Al ser la primera vez, IntelliJ intenta resolver dependencias al detectar los diferentes proyectos maven, pero simplemente cancelamos este proceso ya que durante el primer build, ya se descargaron las dependencias necesarias.
Configurar el SDK
En el menú, en la opción Project structure > Platform Settings, agregamos una nueva entrada haciendo click en el botón ‘+' que verás en la parte superior, selecciona Add JDK from disk y navega hasta el workspace, dentro de la carpeta 'OnesaitPlatform-Workspace/tools/windows/’ dónde encontrarás el JDK versión 8 y 17. En este caso usamos la 17, sólo debes seleccionar la carpeta raíz (jdk-17 o jdk-8) y hacer click en Apply.
El resultado trás añadir el JDK que debes ver es el siguiente:
Ahora vamos a Project Structure > Project Settings para seleccionar el SDK recién añadido, desde el desplegable de SDK seleccionamos, aplicamos y listo.
Es posible que en algún momento necesites usar la versión 8, añadirla sería exactamente lo mismo que acabamos de hacer.
Configurar Maven
Ahora es el turno de Maven, lo primero que debemos hacer, es una pequeña modificación a nuestro fichero settings.xml ubicado en ‘OnesaitPlatform-Workspace/config/maven', abrimos el fichero y modificamos el valor de localRepository (Introduce la ruta en la que tengas tu workspace situado).
Hecho esto, vamos al menú de nuevo, en la opción Settings > Build, Execution, Deployment > Build Tools > Maven (o simplemente escribe Maven en el buscador ), y configuramos de la siguiente manera:
Usaremos Maven de la carpeta ‘OnesaitPlatform-Workspace/tools/windows/maven’, el fichero settings de ‘OnesaitPlatform-Workspace/config/maven/settings.xml’ y verificamos que la ruta del repositorio se haya actualizado de forma automática al directorio m2_repo del workspace trás seleccionar el fichero settings.xml.
Para finalizar, debemos elegir el JRE correcto para maven, lo cual es configurable desde la sección Runner dentro de la configuración del mismo Maven.
Paso 4: Preparar las Bases de Datos
Levantar Servidores y Clientes
Para que nuestra plataforma pueda funcionar en local, necesitaremos de una base de datos Mysql (Mariadb) y una Mongo. Para ello, ejecuta el comando
docker compose up -d mongodb mariadb mongo-express adminer y en unos segundos o minutos, verás que se han levantado 4 contenedores diferentes, 2 para las bases de datos y otros dos clientes UI (Adminer para SQL y Mongo Express para Mongo).
Te recomiendo ejecutar docker ps y verificar que los servicios están funcionando correctamente, a veces alguno puede no iniciar por algún error. Intenta lanzar el mismo comando docker compose y si con esto no consigues que todos los servicios estén corriendo, habrá que inspeccionar los logs del afectado en busca del problema. https://docs.docker.com/reference/cli/docker/container/logs/
Aquí te dejo una lista de los servicios, los puertos en los que escucha y sus credenciales:
Servicio | Url | Credenciales |
|---|---|---|
Mongo Express | admin:password | |
Mongo | username:password | |
Adminer | - | |
MariaDB | root:changeIt! |
También puedes encontrar esta información en el fichero docker-compose.yaml
Popular y Configurar las Bases de Datos
La Plataforma tiene una ConfigDB donde almacena todas sus configuraciones.
Para que funcione la plataforma, esta ConfigDB debe estar inicializada (con sus datos de configuración), en este paso vamos a ver cómo inicializarla, esto se hace con el proyecto config-init
La ConfigDB puede cambiar entre major releases. A la hora de desarrollar lo más fácil es borrar en la ConfigDB los esquemas onesaitplatform-config y onesaitplatform-master-config a través del ConfigDB.Browser y volver a inicializarla como vamos a hacer en este paso.
En el IDE vamos al proyecto onesaitplatform-config-init y localizamos la clase SystemConfigInitApplication (en el paquete com.minsait.onesait.platform.systemconfig.init).
Esta clase se encarga de inicializar la plataforma, no sólo la ConfigDB, aunque ahora sólo nos interesa inicializar la ConfigDB.
Sobre la clase, click con el botón derecho y selecciono Run:
Error Running Command Line Too Long
Si ves este error, simplemente haz click en Shorten the command line and rerun y debería funcionar sin problemas.
Para ver si se ha inicializado la ConfigDB puedo mirar los logs en la Consola o acceder a Adminer y ver si las tablas se han populado, por ejemplo en la tabla ontology en el esquema onesaitplatform_config:
Paso 5: Ejecutar Control Panel de Plataforma
Una vez cargados los datos de configuración en la ConfigDB puedo lanzar el Control Panel de Plataforma.
El Control Panel es un módulo de plataforma que no requiere la ejecución de ningún otro para funcionar y ofrece un UI Web, APIs REST de gestión además de actuar como un nodo CacheServer.
En función de la labor que vayamos a hacer sobre el Control Panel puede ser recomendable también tener iniciado el servicio de MongoDB.
Vamos el proyecto onesaitplatform-controlpanel y abrimos el archivo application.yml que se encuentra en /src/main/resources:
Comprobamos que las propiedades authentication.oauth.enabled y authentication.oauth.osp-keycloak están a false, y modificamos su valor en caso contrario
Estas propiedades permiten habilitar/deshabilitar la autenticación con el Keycloak IM de Plataforma, si quisiéramos habilitarla aquí tenemos una guía de como levantarlo en local: https://es.onesaitplatform.com/space/DOC/4120641552/¿Cómo+levantar+Keycloak+como+Identity+Manager+en+Entorno+local%3F
Dentro del proyecto vamos a la clase ControlPanelWebApplication (en paquete com.minsait.onesait.platform.controlpanel)
Sobre la clase, click con el botón derecho y selecciona Run:
Ahora puedo acceder al ControlPanel accediendo a http://localhost:18000/controlpanel/
Puedo acceder al ControlPanel con los usuarios
Paso 6: Ejecutar otros módulos de Plataforma
El ControlPanel es un módulo independiente, el resto de módulos necesitan la ejecución de al menos el módulo CacheServer (proyecto onesaitplatform-cacheserver).
Para arrancar este módulo ejecutaré la clase CacheServerApplication (paquete com.minsait.onesait.platform)
Tras esto puedo ejecutar el resto de módulos de plataforma, los módulos de plataforma se encuentran en la carpeta modules y son estos.
El resto son servicios y librerías que se ejecutan dentro de estos módulos
Problemas Conocidos
Mongo Command Failed With Error 13 (Unauthorized)
Si ves un error como este, durante el paso para popular las bases de datos:
La solución pasa por añadir la propiedad useAuth: true dentro de onesaitplatform > database > mongodb en el fichero properties.yml del módulo config-init, como se puede apreciar en la imagen. Hecho esto, vuelve a ejecutar el SystemConfigInitApplication y no deberías volver a ver este problema.
¡Eso es todo! ¡¡¡Esperamos que lo disfrutes!!!