LYCloud (LYSaaS)

Manual de referencia y uso

Convenciones

Para este documento, se supone que LYSaaS se encuentra instalado en /opt/lysaas.

Importante

Para una referencia rápida sobre cómo crear nuevas instancias o instalar un componente sobre las actuales, revisar directamente el apartado Generación de una nueva instancia SaaS y el apartado Instalación / actualización de un componente en una instancia SaaS.

Configuración de puertos de una instancia

Al ejecutar Configurar.sh, el proceso verificará si dicha instancia es una instancia LYSaaS o no. Esto dependerá de que el archivo /OXP_HOME/utils/saas/cfg/InstanceConfiguration.cfg exista, y que además la propiedad instanceID esté seteada en un valor mayor a 0.

En caso de estar configurado como instancia LY SaaS, la pantalla de configuración impedirá indicar los puertos (1099 para JNP, 8080 para Web, 8443 para SSL), dado que los mismos deben tener estos valores por defecto a fin de poder realizar el shifting de manera automática a partir de dichos valores:

El valor de shifting para cada puerto dependerá de la configuración general de LYSaaS, alojada en el archivo /opt/lysaas/cfg/GeneralConfiguration.cfg, bajo la configuración portStep.

Luego de clickear Guardar, el paso final del Configurar realiza el shifting correspondiente, en función del número de instancia:

Como el proceso tiene que ser idempotente, es por eso que en el archivo LibertyaEnv.properties mantiene los valores originales 1099, 8443 y 8080 para los puertos; a partir de los cuales es posible aplicar el corrimiento cuantas veces sea necesario, incluso si se cambia el instanceID a un valor distinto. Es por ésto que en dicho archivo quedan guardados los valores sin el corrimiento.

IMPORTANTE: Dada la lógica del script, si por ejemplo se modifica el número de instancia o el portStep, no es suficiente con disparar el proceso setInstancePort.sh para modificar una instancia ya shifteada dado que el script buscará los valores originales de los puertos (1099, 8080, etc.); será necesario ejecutar nuevamente Configurar.sh en este caso para luego sí ejecutar el shifting.

Nota: como regla general es posible invocar el shifting las veces que sea necesario utilizando el script /opt/lysaas/bin/setInstancePorts.sh <número_de_instancia>. Como requisito, es necesario que la instancia sea configurada mediante Configurar.sh previamente.

Nota: Del mismo modo, también es factible ejecutar ConfigurarAuto.sh, el cual realizará la misma operatoria. Como requisito, es necesario que la instancia al menos haya sido configurada mediante Configurar.sh al menos una vez, siempre y cuando no se modifique la configuración del número de instancia o portStep.

Nota: Para finalizar la ejecución de alguna instancia JBoss correctamente, es necesario contar al menos con la revisión 1383 de LY Standard, dado que ese commit incluye una corrección que permite especificar un puerto JNP distinto al tradicional (1099).

Inicio automático JBoss de una instancia

Para poder especificar que una instancia de Libertya inicie automáticamente, se deberá utilizar el script /opt/lysaas/bin/deployAutostartDaemon.sh. Este script realiza las siguientes actividades:

1. Copia desde el directorio template el archivo libertyad hacia /etc/init.d, concatenándole al final el número de instancia. Por ejemplo libertyad pasa a ser libertyad1.
   
2. Modifica el archivo recién copiado, reemplazando por ejemplo /ServidorOXP por /ServidorOXP1 y libertya.pid por libertya1.pid (lógicamente según el número de instancia pasado)
   
3. Invoca al comando correspondiente para registrar al script como un servicio (esto dependiendo de la distribución Linux en donde se esté trabajando).

Recibe un unico argumento (obligatorio):

1. Número de instancia sobre la cual desea aplicarse el script (1, 2… etc.); el cual será utilizado para realizar el renombre de archivos correspondiente.

Ejemplo:

Nota: El script libertyad es tomado a partir del directorio template, cuya ubicación base debe estar correctamente especificado en el archivo /opt/lysaas/cfg/GeneralConfiguration.cfg, bajo la propiedad templateLocation. Al momento de escribir este manual, el archivo libertyad base es el correspondiente a la revisión 1383 de LY Standard.

IMPORTANTE: Se debe configurar la osPlatform en /opt/lysaas/cfg/GeneralConfiguration.cfg, indicando si la distribución del S.O. es Debian o RedHat. A partir de dicha configuración, se ejecutará el script de manera acorde.

IMPORTANTE: El ant job definido utiliza chkconfig (bajo RedHat) o update-rc.d (bajo Debian) para incluir el script al iniciar el sistema. Adicionalmente, el script de inicio automático utiliza la funcionalidad start-stop-daemon para lograr esta tarea. Por consiguiente, es importante garantizar que estas aplicaciones se encuentran instaladas en el equipo previamente a utilizar el deployAutostartDaemon.

Generación de una nueva instancia SaaS

A fin de poder generar una nueva instancia de Libertya SaaS, se cuenta con el script newInstance.sh. El mismo se apoya en los templates de deploy existentes, en función de las necesidades funcionalidades del caso (versión de LY CORE, localización, etc.). Al invocar el script se deberá seleccionar el template de deploy correspondiente. Por ejemplo:

El script recibe entonces 2 argumentos:

1. Número de instancia a generar. Esto definirá el nombre del directorio de Libertya (por ejemplo ServidorOXP8) y el nombre de la base de datos (por ejemplo libertya_prod8).
   
2. Ubicación del archivo de deploy con las actividades a realizar. En el ejemplo se instalará la versión 15.03 de Libertya CORE, más la localización Argentina, versión 1.5, más Conjunto de Atributos, versión 1.2. Los templates de deploy actualmente existentes residen en el directorio /opt/lysaas/deploy

El script principal en conjunto con el script de instalación realizan todas las actividades necesarias:

1. Copia del template correspondiente desde el repositorio de binarios
   
2. Copia del template correspondiente desde el repositorio de BBDD
   
3. Instalación de componentes adicionales
   
4. Configuraciones a nivel BBDD si correspondiera
   
5. Configuración del servidor
   
6. Shifting de puertos
   
7. Configuración automática de inicio de JBoss al iniciar el equipo

Lógicamente, las actividades a realizar variarán según el archivo de deploy seleccionado. Una vez finalizadas las actividades, el último paso del script principal es el de dejar iniciado el servidor de la nueva instancia mediante service libertyad8 start.

NOTA: el nombre base de la base de datos se encuentra definido en el archivo general de configuración /opt/lysaas/cfg/GeneralConfiguration.cfg, bajo la propiedad instanceBaseDBName (por ejemplo libertya_prod, al cual luego se concatenará el numero de instancia)

Instalación / actualización de un componente en una instancia SaaS

A fin de poder actualizar una instancia de Libertya SaaS, se cuenta con el script installUpgrade.sh. El mismo se apoya en los templates de deploy existentes, en función de la disponibilidad de componentes existente. Al invocar el script se deberá seleccionar el template de actualización correspondiente. Por ejemplo:

El script recibe entonces 2 argumentos:

1. Número de instancia/s a actualizar (si es más de una, deberán estar separadas por coma sin dejar espacios).
   
2. Ubicación del archivo de deploy con las actividades a realizar. En el ejemplo se instalará la versión 1.0 de Facturación Masiva. Los templates de actualización actualmente existentes residen en el directorio /opt/lysaas/upgrade

El script principal en conjunto con el script de actualización realizan todas las actividades necesarias:

1. Detener el servidor correspondiente según el número de instancia
   
2. Copia de los binarios que sean necesarios
   
3. Instalación del componente a nivel BBDD
   
4. Configuración adicionales post-instalación
   
5. Reiniciar el servidor

Ejecución de sentencias SQL

Para la ejecución de sentencias SQL a una o varias instancias, es posible utilizar el script queryFile.sh. El mismo permite definir las instancias sobre las cuales ejecutar la o las sentencias SQL, las cuales deben estar almacenadas en un archivo para tal fin. Por ejemplo:

El script recibe entonces 2 argumentos:

1. Número de instancia/s a actualizar (si es más de una, deberán estar separadas por coma sin dejar espacios).
   
2. Ubicación del archivo SQL con las sentencias a ejecutar.

El script ejecutará el conjuno de sentencias especificado en el archivo sobre cada una de las instancias especificadas como argumento.

Backup de instancias

Es posible realizar copias de respaldo de las instancias mediante una simple invocación:

backupInstance.sh <número_de_instancia>

El proceso se encargará de:

1. Generar, comprimir y copiar a destino un dump de la base de datos para la instancia en cuestión
   
2. Comprimir y copiar a destino el ServidorOXP para la instancia en cuestión
   
3. Comprimir y copiar a destino el directorio de factura eletrcónica para la instancia en cuestión (si es que este existe)

La ubicación destino es configurada en el archivo GeneralConfiguration.cfg, bajo las siguientes propiedades:

• backupUser: Usuario del host en donde se almacenan los backups
  
• backupHost: Host en donde se almacenan los backups
  
• backupPort: Port de conexion en donde se almacenan los backups
  
• backupDir: Ubicacion en donde se almacenan los backups
  
• backupDateSuffix: Sufijo de fecha de los archivos de backup

La propiedad backupDateSuffix es un valor que respeta java.text.SimpleDateFormat y permite especificar un sufijo de fecha para cada archivo, lo cual brinda completa libertad en cuanto al número de backups por instancia a salvaguardar.

Por ejemplo, si no se especifica sufijo alguno y se realizaran backups diarios, el backup será pisado diariamente. Si por el contrario se indca que el sufijo sea el día de la semana, se tendrá 7 backups por instancia (que luego serán pisados con el correr del tiempo por nuevas versiones), y si se indica día del mes, se tendrán 31 backups por instancia.

IMPORTANTE: Debe garantizarse que todas las condiciones se cumplan para realizar la copia de respaldo, o sea: haber generado el usuario en el host destino, permitir acceso SSH mediante el port correspondiente, haber generado el directorio de backups, etc.

IMPORTANTE: Es necesario haber configurado previamente un acceso desatendido (sin prompt de password) al equipo bajo destino para usuario backupUser. Para ésto, en el equipo SaaS deben ejecutarse los siguientes comandos:

ssh-keygen -t rsa (en caso de que no exista clave)
cat /root/.ssh/id_rsa.pub | ssh root@<backupHost> ‘cat >> /root/.ssh/authorized_keys’

Cabe mencionar que debe existir el directorio /root/.ssh en el equipo destino.

Manual del Desarrollador

Definicion de nuevas actividades de deploy y/o upgrade

Para la definición de nuevas actividades, simplemente se deben seguir los lineamientos generales de actividades ant, basándose en alguna actividad preexistente.

Cabe destacar que existe un número predefinido de etapas que se ejecutarán, tanto en un deploy como en un upgrade, a saber:

1. Deploy
   1. deployDatabase: creación de la bbdd a partir de un dump
      
   2. deployBinaries: copia de los archivos binarios (core, componentes, etc.)
      
   3. installPlugins: instalación de los componentes (si corresponde) mediante PluginInstall
      
   4. configureInstance: eventuales actividades adicionales
      
2. Upgrade
   1. deployBinaries: actualización de archivos binarios (ej. nuevo componente)
      
   2. installPlugins: instalación de los componentes (si corresponde) mediante PluginInstall
      
   3. configureInstance: eventuales actividades adicionales

Es importante además respetar la utilización del archivo de configuración con la estructura de archivos disponibles en el template llamado TemplateDefinition.cfg, reflejando en dicho archivo cualquier modificación de la estructura de archivos del template.

Contenido TemplateDefinition.cfg

Este archivo de configuración es parte de la configuracion general de Libertya SaaS. En el mismo se especifican las ubicaciones de los recursos disponibles en la estructurade template disponibles para su utilización en nuevas instancias o actualizaciones. Las actividades correspondientes deberán apoyarse en éste al momento de referenciar recursos del template. Toda modificación en la estructura de archivos del template debera ser reflejada en este archivo de configuración. A continuación se presenta una parte del mismo a modo de ejemplo:

# ====================================================
# ============= BASES DE DATOS DE DEPLOY =============
# ====================================================

# BBDD Libertya 15.03 Internacional
db.core.15.03i.dump=db/core/15.03/dump_libertya_1503.sql

# BBDD Libertya 15.03 LocaleAR
db.core.15.03ar.dump=db/core/15.03/dump_libertya_1503ar.sql

# ==================================================
# ============= BINARIOS LIBERTYA CORE =============
# ==================================================

# Libertya CORE 15.03
bin.core.15.03.ServidorOXP=bin/core/15.03/ServidorOXP_V15.03.zip

# =======================================
# ============= COMPONENTES =============
# =======================================

# ——————-
# — Libertya WS —
# ——————-

# Libertya WS, version 50 la cual se apoya en Libertya CORE 15.03
bin.plugin.LYWS.1503.50=bin/components/lyws/1503.50/org.libertya.ws.axis.war_r50GC.zip