doc: add build and use instructions

Full-Tortuga · Dec 28, 2021 · d2b13ef · d2b13ef
1 parent 3dfc2f5
commit d2b13ef
Showing 1 changed file with 61 additions and 62 deletions.
diff --git 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&amp;utm_medium=referral&amp;utm_content=wadobo/decide&amp;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,34 +45,29 @@ 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
 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:
 
     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).