Diferencia entre revisiones de «Equipo de integración general - 17 18 - G2»
(→Procedimiento general para la gestión de incidencias) |
(→Integración continua y despliegue con Travis CI) |
||
(No se muestran 32 ediciones intermedias de 3 usuarios) | |||
Línea 17: | Línea 17: | ||
Puede acceder a nuestro proyecto en Opera [http://opera.eii.us.es/egc/public/trabajo/ver/id/74 aquí] | Puede acceder a nuestro proyecto en Opera [http://opera.eii.us.es/egc/public/trabajo/ver/id/74 aquí] | ||
− | == Formato para detallar tecnologías elegidas == | + | == Máquina virtual de desarrollo == |
+ | La máquina virtual de desarrollo (descarga [https://drive.google.com/file/d/1nrXjmWwJRuOUIWOtVEZmiqczZaee96Mk/view?usp=sharing 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 === | ||
+ | |||
+ | {| class="wikitable" | ||
+ | !Subsistema | ||
+ | !Dirección IP | ||
+ | !Puerto | ||
+ | |- | ||
+ | |BD Wordpress | ||
+ | |172.18.2.1 | ||
+ | |No publicado al exterior | ||
+ | |- | ||
+ | |BD Sistema de votación | ||
+ | |172.18.2.2 | ||
+ | |3306 | ||
+ | |- | ||
+ | |Wordpress (Portal Jornadas) | ||
+ | |172.18.2.5 | ||
+ | |50000 | ||
+ | |- | ||
+ | |Portal votaciones | ||
+ | |172.18.2.10 | ||
+ | |50010 | ||
+ | |- | ||
+ | |Autenticación | ||
+ | |172.18.2.20 | ||
+ | |50020 | ||
+ | |- | ||
+ | |Administración de censos | ||
+ | |172.18.2.30 | ||
+ | |50030 | ||
+ | |- | ||
+ | |Administración de votaciones | ||
+ | |172.18.2.40 | ||
+ | |50040 | ||
+ | |- | ||
+ | |Almacenamiento de votos | ||
+ | |172.18.2.50 | ||
+ | |50050 | ||
+ | |- | ||
+ | |Cabina de votaciones | ||
+ | |172.18.2.60 | ||
+ | |50060 | ||
+ | |- | ||
+ | |Recuento | ||
+ | |172.18.2.70 | ||
+ | |50070 | ||
+ | |- | ||
+ | |Cabina Telegram | ||
+ | |No | ||
+ | |No | ||
+ | |} | ||
+ | |||
+ | *Para acceder a algún servicio la URL consiste en <nowiki>http://localhost:<puerto></nowiki>. Ej: <nowiki>http://localhost:50000</nowiki> 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 [http://ask.xmodulo.com/access-nat-guest-from-host-virtualbox.html 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". | ||
+ | |||
+ | {| class="wikitable" | ||
+ | !Subsistema | ||
+ | !Nombre de la BD | ||
+ | !Usuario | ||
+ | |- | ||
+ | |Autenticación | ||
+ | |autenticacion | ||
+ | |auth-user | ||
+ | |- | ||
+ | |Administración de censos | ||
+ | |adm_censos | ||
+ | |censos-user | ||
+ | |- | ||
+ | |Administración de votaciones | ||
+ | |AdministracionVotaciones | ||
+ | |acme-user / acme-manager | ||
+ | |- | ||
+ | |Almacenamiento de votos | ||
+ | |almacenamiento | ||
+ | |alm-user | ||
+ | |- | ||
+ | |Recuento | ||
+ | |recuento | ||
+ | |rec-user | ||
+ | |} | ||
+ | |||
+ | === 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: | ||
+ | # Comprobar que en el código se hacen peticiones a la dirección IP de cada subsistema. | ||
+ | # 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. | ||
+ | # 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 [https://github.com/EGC-G2-Trabajo-1718/integracion/blob/master/travis/template.yml 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 [https://github.com/EGC-G2-Trabajo-1718/integracion/ repositorio de integración]. | ||
+ | |||
+ | == Formatos y procedimientos == | ||
+ | |||
+ | === Formato para detallar tecnologías elegidas === | ||
'''Subsistema''': <Nombre del subsistema/equipo> | '''Subsistema''': <Nombre del subsistema/equipo> | ||
'''Lenguaje/Herramienta''': <Lenguaje/herramienta escogida y versión> | '''Lenguaje/Herramienta''': <Lenguaje/herramienta escogida y versión> | ||
Línea 25: | Línea 180: | ||
'''Necesita Base de datos''': <Sí/No> (En caso afirmativo explicar cuál se está empleando y su versión) | '''Necesita Base de datos''': <Sí/No> (En caso afirmativo explicar cuál se está empleando y su versión) | ||
− | == Formato general para detallar incidencias == | + | === 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: | ||
+ | |||
+ | {| border="1" style="border-collapse:collapse" | ||
+ | |- | ||
+ | ! Nombre | ||
+ | ! Tipo | ||
+ | ! Descripción | ||
+ | ! Valor por defecto | ||
+ | |- | ||
+ | | user | ||
+ | | integer | ||
+ | | Nombre del usuario | ||
+ | | | ||
+ | |} | ||
+ | |||
+ | |||
+ | ''' 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: | ||
+ | |||
+ | {| border="1" style="border-collapse:collapse" | ||
+ | |- | ||
+ | ! Nombre | ||
+ | ! Tipo | ||
+ | ! Descripción | ||
+ | |- | ||
+ | | result | ||
+ | | Boolean | ||
+ | | Resultado de la operación | ||
+ | |- | ||
+ | | msg | ||
+ | | String | ||
+ | | Mensaje de resultado o error | ||
+ | |} | ||
+ | |||
+ | |||
+ | ''' 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: | ||
+ | |||
+ | {| border="1" style="border-collapse:collapse" | ||
+ | |- | ||
+ | ! Código | ||
+ | ! Valor result | ||
+ | ! Valor msg | ||
+ | ! Posible motivo | ||
+ | |- | ||
+ | | 200 | ||
+ | | true | ||
+ | | Successfull | ||
+ | | | ||
+ | |- | ||
+ | | 404 | ||
+ | | false | ||
+ | | User not found | ||
+ | | El usuario indicado no existe. | ||
+ | |- | ||
+ | | 403 | ||
+ | | false | ||
+ | | Don't have access | ||
+ | | No tienes permisos para acceder. | ||
+ | |} | ||
+ | |||
+ | |||
+ | === Formato general para detallar incidencias === | ||
Las incidencias pueden emplearse no solo para fallos. | Las incidencias pueden emplearse no solo para fallos. | ||
'''Título''': <breve título sobre la incidencia> | '''Título''': <breve título sobre la incidencia> | ||
Línea 38: | Línea 312: | ||
''question'': (a usar solo entre miembros del equipo) dudas sobre un commit en concreto, hay que referenciar el commit en cuestión | ''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 == | + | === Procedimiento general para la gestión de incidencias === |
# Establecer a un miembro del equipo el rol de gestor de incidencias. | # Establecer a un miembro del equipo el rol de gestor de incidencias. | ||
# Cuando se registre una incidencia, el gestor deberá evaluar la prioridad, asignar las etiquetas correspondientes (si faltasen) y un responsable de la incidencia. | # Cuando se registre una incidencia, el gestor deberá evaluar la prioridad, asignar las etiquetas correspondientes (si faltasen) y un responsable de la incidencia. | ||
Línea 47: | Línea 321: | ||
Estas diapositivas incluyen información complementaria: | Estas diapositivas incluyen información complementaria: | ||
https://github.com/InnosoftDaysPresidencia/Presidencia/raw/master/GitHub/Gu%C3%ADa%20de%20GitHub%20Classroom.pdf | 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 [http://karma-runner.github.io/1.0/dev/git-commit-msg.html 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: | ||
+ | [[File:branch-flow.png|center|thumb|1000px|link=https://1984.lsi.us.es/wiki-egc/images/egc/d/dc/Branch-flow.png]] |
Revisión actual del 19:22 7 ene 2018
Contenido
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
Subsistema | Dirección IP | Puerto |
---|---|---|
BD Wordpress | 172.18.2.1 | No publicado al exterior |
BD Sistema de votación | 172.18.2.2 | 3306 |
Wordpress (Portal Jornadas) | 172.18.2.5 | 50000 |
Portal votaciones | 172.18.2.10 | 50010 |
Autenticación | 172.18.2.20 | 50020 |
Administración de censos | 172.18.2.30 | 50030 |
Administración de votaciones | 172.18.2.40 | 50040 |
Almacenamiento de votos | 172.18.2.50 | 50050 |
Cabina de votaciones | 172.18.2.60 | 50060 |
Recuento | 172.18.2.70 | 50070 |
Cabina Telegram | No | No |
- 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".
Subsistema | Nombre de la BD | Usuario |
---|---|---|
Autenticación | autenticacion | auth-user |
Administración de censos | adm_censos | censos-user |
Administración de votaciones | AdministracionVotaciones | acme-user / acme-manager |
Almacenamiento de votos | almacenamiento | alm-user |
Recuento | recuento | rec-user |
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:
- Comprobar que en el código se hacen peticiones a la dirección IP de cada subsistema.
- 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.
- 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:
Nombre | Tipo | Descripción | Valor por defecto |
---|---|---|---|
user | integer | Nombre del usuario |
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:
Nombre | Tipo | Descripción |
---|---|---|
result | Boolean | Resultado de la operación |
msg | String | Mensaje de resultado o error |
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:
Código | Valor result | Valor msg | Posible motivo |
---|---|---|---|
200 | true | Successfull | |
404 | false | User not found | El usuario indicado no existe. |
403 | false | Don't have access | No tienes permisos para acceder. |
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
- Establecer a un miembro del equipo el rol de gestor de incidencias.
- Cuando se registre una incidencia, el gestor deberá evaluar la prioridad, asignar las etiquetas correspondientes (si faltasen) y un responsable de la incidencia.
- 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: