diff --git a/README.md b/README.md index 5de4858..dada57e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![Build Status](https://travis-ci.com/wadobo/decide.svg?branch=master)](https://travis-ci.com/wadobo/decide) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/94a85eaa0e974c71af6899ea3b0d27e0)](https://www.codacy.com/app/Wadobo/decide?utm_source=github.com&utm_medium=referral&utm_content=wadobo/decide&utm_campaign=Badge_Grade) [![Codacy Badge](https://api.codacy.com/project/badge/Coverage/94a85eaa0e974c71af6899ea3b0d27e0)](https://www.codacy.com/app/Wadobo/decide?utm_source=github.com&utm_medium=referral&utm_content=wadobo/decide&utm_campaign=Badge_Coverage) +[![Build Status](https://travis-ci.com/wadobo/decide.svg?branch=master)](https://travis-ci.com/wadobo/decide) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/94a85eaa0e974c71af6899ea3b0d27e0)](https://www.codacy.com/app/Wadobo/decide?utm_source=github.com&utm_medium=referral&utm_content=wadobo/decide&utm_campaign=Badge_Grade) [![Codacy Badge](https://api.codacy.com/project/badge/Coverage/94a85eaa0e974c71af6899ea3b0d27e0)](https://www.codacy.com/app/Wadobo/decide?utm_source=github.com&utm_medium=referral&utm_content=wadobo/decide&utm_campaign=Badge_Coverage) Plataforma voto electrónico educativa @@ -11,17 +11,14 @@ votación, por lo que prima la simplicidad por encima de la eficiencia cuando sea posible. Por lo tanto se asumen algunas carencias para permitir que sea entendible y extensible. - -Subsistemas, apps y proyecto base ---------------------------------- +## Subsistemas, apps y proyecto base El proyecto se divide en [subsistemas](doc/subsistemas.md), los cuales estarán desacoplados entre ellos. Para conseguir esto, los subsistemas se conectarán entre si mediante API y necesitamos un proyecto base donde configurar las ruts de estas API. Este proyecto Django estará dividido en apps (subsistemas y proyecto base), donde cualquier app podrá ser reemplazada individualmente. -Gateway -------- +## Gateway Para ofrecer un punto de entrada conocido para todos los subsistemas existe el llamado **gateway** que no es más que una ruta disponible @@ -48,8 +45,7 @@ gateway es útil para hacer uso desde peticiones de cliente, por ejemplo en el javascript de la cabina de votación o la visualización de resultados, y también para módulos externos que no sean aplicaciones django. -Configurar y ejecutar el proyecto ---------------------------------- +## Configurar y ejecutar el proyecto Para configurar el proyecto, podremos crearnos un fichero local_settings.py basado en el local_settings.example.py, donde podremos configurar la ruta de nuestras apps o escoger que módulos @@ -57,17 +53,13 @@ ejecutar. Se hará uso de la base de datos MongoDB, para el correcto funcionamiento de la aplicación será necesaria la instalación de dicha base de datos siguiendo las instrucciones de la documentación oficial según el SO que estemos utilizando: -Windows: - - https://docs.mongodb.com/manual/tutorial/install-mongodb-on-windows/ +Windows: - https://docs.mongodb.com/manual/tutorial/install-mongodb-on-windows/ -Ubuntu: - - https://docs.mongodb.com/manual/tutorial/install-mongodb-on-ubuntu/ +Ubuntu: - https://docs.mongodb.com/manual/tutorial/install-mongodb-on-ubuntu/ -WSL: - - https://docs.microsoft.com/es-es/windows/wsl/tutorials/wsl-database#install-mongodb +WSL: - https://docs.microsoft.com/es-es/windows/wsl/tutorials/wsl-database#install-mongodb -MacOs: - - https://docs.mongodb.com/manual/tutorial/install-mongodb-on-os-x/ +MacOs: - https://docs.mongodb.com/manual/tutorial/install-mongodb-on-os-x/ Una vez hecho esto, y corriendo la base de datos, será necesario instalar las dependencias del proyecto, las cuales están en el fichero requirements.txt: @@ -75,7 +67,7 @@ fichero requirements.txt: pip install -r requirements.txt En caso de fallo al instalar las dependencias, es necesario instalas el paquete wheel y volver al comando anterior: - pip install wheel +pip install wheel Entramos en la carpeta del proyecto (cd decide) y realizamos las migraciones correspondientes para preparar la base de datos: @@ -87,7 +79,7 @@ A continuación, entramos en la carpeta del panel (cd decide_panel) y ejecutamos npm install -Situados en el directorio raíz del proyecto, entramos en la carpeta del proyecto (cd decide) y +Situados en el directorio raíz del proyecto, entramos en la carpeta del proyecto (cd decide) y realizamos la primera migración para preparar la base de datos que utilizaremos: ./manage.py makemigrations @@ -102,24 +94,38 @@ También debemos lanzar el panel de control, para ello dentro de la carpeta deci npm start -Ejecutar con docker -------------------- +## Nuevo panel de administración + +Para configurar el nuevo panel de control de administración se deben seguir los siguientes pasos. (se deben haber instalado los nuevos requirements y configurado la nueva base de datos tal y como se describe previamente) + +Se recuerda que se debe copiar el archivo de configuración local de ejemplo: + +- `cp local_settings.example.py local_settings.py` + +### setup + +- `cd /decide/administration/frontend` +- `npm install && npm run build` +- abrir `http://localhost:8000/administration` en el navegador +- hacer login con un superusuario + +## Ejecutar con docker Existe una configuración de docker compose que lanza 3 contenedores, uno para el servidor de base de datos, otro para el django y otro con un servidor web nginx para servir los ficheros estáticos y hacer de proxy al servidor django: - * decide\_db - * decide\_web - * decide\_nginx +- decide_db +- decide_web +- decide_nginx Además se crean dos volúmenes, uno para los ficheros estáticos y medias del proyecto y otro para la base de datos postgresql, de esta forma los contenedores se pueden destruir sin miedo a perder datos: - * decide\_db - * decide\_static +- decide_db +- decide_static Se puede editar el fichero docker-settings.py para modificar el settings del proyecto django antes de crear las imágenes del contenedor. @@ -149,8 +155,7 @@ Lanzar una consola SQL: $ docker exec -ti decide_db ash -c "su - postgres -c 'psql postgres'" -Ejecutar con vagrant + ansible ------------------------------- +## Ejecutar con vagrant + ansible Existe una configuración de vagrant que crea una máquina virtual con todo lo necesario instalado y listo para funcionar. La configuración está en @@ -185,8 +190,7 @@ Eliminar la máquina virtual: $ vagrant destroy -Ansible -------- +## Ansible El provisionamiento de la aplicación con vagrant está hecho con Ansible, algo que nos permite utilizarlo de forma independiente para provisionar @@ -203,13 +207,13 @@ Los scripts de ansible están divididos en varios ficheros .yml donde se definen las diferentes tareas, por lo que es posible lanzar partes independientes: - * packages.yml, dependencias del sistema - * user.yml, creación de usuario decide - * python.yml, git clone del repositorio e instalación de dependencias python en virtualenv - * files.yml, ficheros de configuración, systemd, nginx y local\_settings.py - * database.yml, creación de usuario y base de datos postgres - * django.yml, comandos django básicos y creación de usuario admin - * services.yml, reinicio de servicios, decide, nginx y postgres +- packages.yml, dependencias del sistema +- user.yml, creación de usuario decide +- python.yml, git clone del repositorio e instalación de dependencias python en virtualenv +- files.yml, ficheros de configuración, systemd, nginx y local_settings.py +- database.yml, creación de usuario y base de datos postgres +- django.yml, comandos django básicos y creación de usuario admin +- services.yml, reinicio de servicios, decide, nginx y postgres Por ejemplo este comando sólo reinicia los servicios en el servidor: @@ -219,8 +223,7 @@ El provisionamiento de ansible está diseñado para funcionar con **ubuntu/bioni para funcionar con otras distribuciones es posible que haga falta modificar el fichero packages.yml. -Versionado ----------- +## Versionado El versionado de API está hecho utilizando Django Rest Framework, y la forma elegida para este versionado es mediante [parámetros de búsqueda](https://www.django-rest-framework.org/api-guide/versioning/#queryparameterversioning), @@ -235,7 +238,6 @@ Si nosotros queremos que la salida que nos da la llamada a la API /voting/, sea diferente en la versión 2, solo tenemos que comprobar en la versión nos está llegando, y hacer lo que queramos, por ejemplo: - ``` def get(self, request, *args, **kwargs): version = request.version # Con request.version obtenemos la versión @@ -249,12 +251,10 @@ llegando, y hacer lo que queramos, por ejemplo: Para llamar a las diferentes versiones, haremos lo siguiente: -* /voting/?version=v1 -* /voting/?version=v2 +- /voting/?version=v1 +- /voting/?version=v2 - -Test de estrés con Locust -------------------------- +## Test de estrés con Locust Antes de empezar, comentaré para que sirven las pruebas de estrés. A veces necesitamos soportar que nuestra aplicación ofrezca una cantidad de peticiones por segundo, porque habrá mucha gente entrando @@ -271,7 +271,7 @@ Para ejecutar los test de estrés utilizando locust, necesitaremos tener instala Una vez instalado, necesitaremos tener un fichero locustfile.py donde tengamos la configuración de lo que vamos a ejecutar. En nuestro caso, tenemos hecho dos ejemplos: -1. Visualizer: entra en el visualizador de una votación para ver cuantas peticiones puede aguantar. +1. Visualizer: entra en el visualizador de una votación para ver cuantas peticiones puede aguantar. Para ejecutar el test de Visualizer, tenemos que tener en cuenta que entra en la votación 1, por lo que necesitaremos tenerla creada para que funcione correctamente, una vez hecho esto, podemos @@ -284,34 +284,33 @@ lo que vamos a ejecutar. En nuestro caso, tenemos hecho dos ejemplos: queremos que vaya creciendo hasta llegar a ese número. Por ejemplo, si ponemos 100 y 5, estaremos creando 5 nuevos usuarios cada segundo hasta llegar a 100. -2. Voters: utilizaremos usuarios previamente creados, y haremos una secuencia de peticiones: login, -getuser y store. Sería lo que realizaría un usuario cuando va a votar, por lo que con este ejemplo -estaremos comprobando cuantas votaciones podemos hacer. - +2. Voters: utilizaremos usuarios previamente creados, y haremos una secuencia de peticiones: login, + getuser y store. Sería lo que realizaría un usuario cuando va a votar, por lo que con este ejemplo + estaremos comprobando cuantas votaciones podemos hacer. - Para ejecutar el test de Voter, necesitaremos realizar varios preparos. Necesitaremos la votación 1 - abierta, y necesitaremos crear una serie de usuarios en el censo de esta votación, para que cuando - hagamos el test, estos usuario puedan autenticarse y votar correctamente. Para facilitar esta - tarea, hemos creado el script de python gen_census.py, en el cual creamos los usuarios que - tenemos dentro del fichero voters.json y los añadimos al censo utilizando la librería requests. - Para que este script funcione, necesitaremos tener instalado request: + Para ejecutar el test de Voter, necesitaremos realizar varios preparos. Necesitaremos la votación 1 + abierta, y necesitaremos crear una serie de usuarios en el censo de esta votación, para que cuando + hagamos el test, estos usuario puedan autenticarse y votar correctamente. Para facilitar esta + tarea, hemos creado el script de python gen_census.py, en el cual creamos los usuarios que + tenemos dentro del fichero voters.json y los añadimos al censo utilizando la librería requests. + Para que este script funcione, necesitaremos tener instalado request: - $ pip install requests + $ pip install requests - Una vez instalado, ejecutamos el script: + Una vez instalado, ejecutamos el script: - $ python gen_census.py + $ python gen_census.py - Tras esto, ya podremos comenzar el test de estrés de votantes: + Tras esto, ya podremos comenzar el test de estrés de votantes: - $ locust Voters + $ locust Voters Importante mirar bien el fichero locustfile.py, donde existen algunas configuraciones que podremos cambiar, dependiendo del HOST donde queramos hacer las pruebas y del id de la votación. A tener en cuenta: -* En un servidor local, con un postgres que por defecto nos viene limitado a 100 usuarios +- En un servidor local, con un postgres que por defecto nos viene limitado a 100 usuarios concurrentes, cuando pongamos más de 100, lo normal es que empiecen a fallar muchas peticiones. -* Si hacemos las pruebas en local, donde tenemos activado el modo debug de Django, lo normal es que +- Si hacemos las pruebas en local, donde tenemos activado el modo debug de Django, lo normal es que las peticiones tarden algo más y consigamos menos RPS (Peticiones por segundo).