Equipo de integración general - 17 18 - G2

Miembros

• Gonzalo Delgado Chaves
• Jesús Rivas Jiménez
• Javier Sánchez Parra
• Mohammed Alaoui Mhammedi
• Roberto García Calero

Repositorio GitHub

El repositorio de GitHub del equipo será accesible aquí

Opera

Puede acceder a nuestro proyecto en Opera aquí

Máquina virtual de desarrollo

La máquina virtual de desarrollo (descarga aquí) permite a cada equipo desarrollar su trabajo en local y comprobar como se integra con el resto de subsistemas. La máquina virtual comparte una serie de puertos con el equipo anfitrión para conseguir la comunicación.

Descripción de IPs y puertos

• Para acceder a algún servicio la URL consiste en http://localhost:<puerto>. Ej: http://localhost:50000 para acceder al portal wordpress.

• Para comunicarse con la API de algún subsistema es necesario especificar la dirección IP de dicho subsistema.

• Las direcciones IPs deben estar presentes en el código publicado en el repositorio remoto, pero durante el desarrollo en local se pueden hacer peticiones a localhost gracias al mapeo de puertos entre el sistema anfitrión y la máquina virtual.

• Todos los subsistemas deben estar configurados para recibir peticiones al puerto 80 (HTTP). Si este aspecto se configura en un fichero del proyecto, es responsabilidad del equipo realizar dicho cambio. En la mayoría de los subsistemas esto ha sido conseguido mediante configuraciones de los contenedores, pero en otros subsistemas es necesario que el equipo revise su código para realizar modificaciones.

• No hay nombres de dominio para los subsistemas, puesto que se encuentran en una red privada y por motivos de seguridad sus servicios no son expuestos al exterior. Cabe recordar el principal consumidor de las APIs de los subsistemas será el portal web del sistema de votaciones.

• Aunque la BD del sistema de votaciones tenga un puerto publicado en Docker, se necesita hacer un mapeo en la máquina virtual. En esta guía hay información de cómo hacerlo. Basta con establecer el puerto anfitrión y el puerto invitado a 3306.

Conexiones a bases de datos

Todas las conexiones se realizan a través del puerto predeterminado de MySQL (3306). Cada equipo debe realizar las configuraciones necesarias en su proyecto para que se puedan conectar a las bases de datos correspondientes. Cuando el contenedor de la base de datos del sistema de votaciones se inicializa por primera vez, se crean las bases de datos necesarias por lo que no se espera que un equipo tenga que interactuar con la base de datos en lo que a configuraciones se refiere. En todos los casos la contraseña de acceso es "egc".

Configuración de la máquina

Nota: la máquina ha sido exportada como un servicio virtualizado de VirtualBox.

• Número de CPUs: 2
• RAM Reservada: 1536MB
• SO: Debian 9 (Stretch)
• Usuario: egc
• Contraseña: egc
• Tiene Docker y Docker Compose instalados

Scripts de automatización

Dado que el objetivo principal de la máquina virtual es contar con un entorno de pruebas lo más parecido al de producción (pre-producción), se han creado varios scripts que automatizan todos los procesos de despliegue de los subsistemas en contenedores. Para contar con estos scripts debemos ejecutar los siguientes comandos en la shell de la máquina virtual:

cd ~/scripts/ # Alt Gr + 4 para conseguir el caracter "~"
git clone https://github.com/EGC-G2-Trabajo-1718/integracion.git

Con estos comandos descargaremos el repositorio de integración, dentro de la carpeta tools se encuentra una serie de scripts de automatización. Para acceder a ellos basta con ejecutar lo siguiente:

cd ~/scripts/integracion/tools
ls # El comando "ls" lista los ficheros existentes en el directorio actual.

Nota: dado que hemos descargado el repositorio de integración podemos obtener versiones más recientes de los scripts ejecutando "git pull".

Script de inicio general

Entre los ficheros de la carpeta tools se encuentra el script de inicio general "start.sh". Este script descarga los repositorios de los distintos subsistemas en la rama especificada por el usuario e inicia un contenedor por cada subsistema con el código descargado. Para iniciar el script escribiremos el siguiente comando:

bash ~/scripts/integracion/tools/start.sh
bash start.sh # En caso de estar situados dentro de la carpeta "tools".

Nota: en muchos casos no es necesario tener desplegados todos los subsistemas, podemos parar la ejecución de los mismos usando el comando "docker stop <nombre_contenedor>".

Script de despliegue temporal

IMPORTANTE: Antes de ejecutar este script debemos comprobar en la configuración de la máquina virtual en VirtualBox que hemos especificado un directorio compartido para copiar en él la carpeta del repositorio con los cambios que hemos hecho en el código. Este script realiza las mismas tareas que el script de inicio general, pero con la diferencia de que permite iniciar un contenedor dentro de la máquina virtual con el código modificado en tu máquina local para realizar diversas pruebas. Los pasos a realizar para ejecutar este script son los siguientes:

1. Comprobar que en el código se hacen peticiones a la dirección IP de cada subsistema.
2. Realizar una copia del directorio raíz del repositorio. Con esto nos referimos a la carpeta resultante de hacer un "clone" del repositorio, no puede ser una carpeta de dentro del repositorio como "src" o derivados. Esta copia debe guardarse en el directorio compartido entre el sistema anfitrión y la máquina virtual.
3. Ejecutar el script en la máquina virtual mediante el siguiente comando:

bash ~/scripts/integracion/tools/deploy-shared.sh
bash deploy-shared.sh # Suponiendo que estamos situados dentro del directorio "tools"

Nota: debido a los distintos procesos que realizan los scripts, el despliegue de todos los proyectos toma bastante tiempo, además varía en función de la velocidad de la red y del rendimiento de tu equipo.

Integración continua y despliegue con Travis CI

Para realizar tareas de integración continua y despliegue continuo se usa la herramienta Travis CI. Con objeto de facilitar las operaciones en este ámbito, se ha creado una plantilla del fichero de configuración de Travis (.travis.yml) que los distintos equipos deben incorporar a sus repositorios (con algunas excepciones). Travis realizará un despliegue del subsistema en el servidor de producción de las construcciones satisfactorias en la rama "master".

Para que Travis pueda realizar el despliegue remoto de un subsistema, el equipo de integración añadirá a los repositorios un fichero encriptado.

La plantilla del fichero .travis.yml se encuentra aquí.

Lista de nombres que admite el script:

• portal-votaciones
• autenticacion
• adm_censos
• adm_votaciones
• almacen_votos
• cabina_votaciones
• cabina_votaciones_telegram
• recuento_votos

Notas:

• Si tu equipo no trabaja con la base de datos del sistema de votaciones se deben omitir las líneas anteriores a "before_install". Sin embargo, es importante que la fase "before_install" siga presente con la línea que hace referencia a la desencriptación del fichero "deploy.enc".
• Falta la fase principal "script", en Travis esta fase es en la que se ejecutan las pruebas unitarias y otros tests. Cada equipo debe saber cómo ejecutar tests mediante los comandos de la herramienta pertinente (mvn, composer, node...), esto es responsabilidad de cada equipo. No se espera que en esta fase se realicen pruebas de integración con otros subsistemas, puesto que desplegar los subsistemas necesarios puede llevar a construcciones de código mucho más lentas, para ello se cuenta con la máquina virtual.
• Es importante comprobar en las primeras construcciones de la rama master que el código se despliega en la máquina de producción. Pueden haber presentes fallos en el script de despliegue que imposibiliten el despliegue del código a producción. En esos casos se deben registrar incidencias en el repositorio de integración.

Formatos y procedimientos

Formato para detallar tecnologías elegidas

Subsistema: <Nombre del subsistema/equipo>
Lenguaje/Herramienta: <Lenguaje/herramienta escogida y versión>
Sistema de gestión de bibliotecas: <Herramienta que se usa para añadir bibliotecas/dependencias> (Ej: Java->Maven, Python->pip)
Bibliotecas: <Listado de bibliotecas usadas en el desarrollo.>
   Nombre_Biblioteca1: <versión>
Necesita Base de datos: <Sí/No> (En caso afirmativo explicar cuál se está empleando y su versión)

Formato para detallar API

URL base Ruta completa incluido el dominio (Ej: https://censo.nvotesus.es/api/v1, https://censo.nvotesus.es/api)

Por cada ruta de la API:

URL relativa

Ruta relativa en base a la URL anterior (Ej: /getUser, /storeVote)

Descripción

Descripción de la tarea que realiza la ruta

Petición HTTP

Indicar el método HTTP usado (Ej: GET, POST, PUT, DELETE)

Parámetros de petición

Parametros que puede recibir indicando el nombre, tipo, descripción y valor por defecto (Si tiene valor por defecto significara que es opcional).

Por ejemplo:

Ejemplo de petición

Ejemplo de uso de la url (Ej: GET https://auth.nvotesus.es/api/v1/get?user=test)

Respuesta

Parametros que puede recibir indicando el nombre, tipo, descripción. Será obligatorio incluir los parametros result y msg

Por ejemplo:

Ejemplo de respuesta

Ejemplo de la respuesta a recibir.

{
  "result" : true,
  "msg" : "Successfull"
  "username" : "tansalalv",
  "name" : "Tania",
  "surname" : "Salguero Álvarez",
  "email" : "mail@example.com",
  "genre" : "Femenino",
  "autonomous_community" : "Andalucía",
  "age" : "21",
  "role" : "USUARIO"
}

Códigos de error

Códigos de error que puede devolver el método indicando el código HTTP, valor de result, valor del mensaje y una breve explicación de porque ha podido pasar.

Por ejemplo:

Formato general para detallar incidencias

Las incidencias pueden emplearse no solo para fallos.

Título: <breve título sobre la incidencia>
Prioridad: a seleccionar entre distintos valores: urgente, alto, medio, bajo.
Estado: pendiente, en curso, finalizado. Los dos primeros estados deberían meterse como etiquetas en GitHub, el último estado se prouduce cuando se cierra la incidencia en GitHub.
Descripción: <descripción detallada del error>
   La descripción puede incluir imagenes o la salida emitida por el fallo.
Etiquetas: <etiquetas de GitHub para clasificar las incidencias>
   enhancement: propuesta de mejora
   bug: fallos encontrados en el sistema
   help wanted: incidencia que puede ser resuelta por un miembro del equipo pero que ha sido atendida previamente por otro
   question: (a usar solo entre miembros del equipo) dudas sobre un commit en concreto, hay que referenciar el commit en cuestión

Procedimiento general para la gestión de incidencias

1. Establecer a un miembro del equipo el rol de gestor de incidencias.
2. Cuando se registre una incidencia, el gestor deberá evaluar la prioridad, asignar las etiquetas correspondientes (si faltasen) y un responsable de la incidencia.
3. El responsable trabajará en la incidencia. Si un commit cierra una incidencia deberá incluir en el cuerpo del commit "Closes #<id de la incidencia>"

Las incidencias pueden incluirse en Proyectos de GitHub.

Estas diapositivas incluyen información complementaria: https://github.com/InnosoftDaysPresidencia/Presidencia/raw/master/GitHub/Gu%C3%ADa%20de%20GitHub%20Classroom.pdf

Formato general de commits

El formato general de los commits parte de la siguiente base.

Es importante diferenciar entre los tipos (types) y usar todos en la medida de lo posible. Los ámbitos o focos (scopes) pueden emplearse para hacer referencia a distintas funcionalidades (features).

A continuación se detalla un ejemplo:

Título del commit: fix: redirección errónea tras emitir voto
Cuerpo del commit: Después de que el usuario emitiese su voto este era redireccionado a una URL no existente. Ahora el usuario es redireccionado al panel principal.
Pie del commit: Closes #<número de la incidencia en GitHub>

Ejemplo en texto:

fix: redirección errónea tras emitir voto

Después de que el usuario emitiese su voto este era redireccionado a una URL no existente. Ahora el usuario es redireccionado al panel principal.

Closes #19

Gestión de ramas

Cada equipo debe establecer una metodología de gestión de ramas. A continuación ponemos un ejemplo de gestión de ramas: