diff --git a/README.md b/README.md index e69de29..8cfce80 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,178 @@ +# Encuestas + +Aplicación desarrollada en Python (Flask) para la gestión de Encuestas on-line. + +Esta preparada para ejecutarse en Contenedores + +Estructura base de la aplicación: + +``` +. +├── app.py +└─── encuestas + ├── fichero-01.encuesta + └── otro_fichero.encuesta +``` + +## Directorio de Encuestas + +Cuando está en ejecución, la aplicacion `app.py` busca en el directorio `data` todos los ficheros con extensión `.encuesta` + +En la ejecución montamos el directorio **`encuestas`** como volumen **`data`** en el contenedor. +Esto nos permite ir modificando o creando nuevas encuestas sin necesidad de reiniciar la aplicación. + +## Visualización de Encuestas + +Si no hay ningun fichero `.encuestas` se muestra una página similar a esta: + +![](imagenes/01-panel-vacio.png) + +Si encuentra ficheros, se revisa el valor del campo `activa` que puede ser `true` o `false` +Este valor determina si la encuesta se encuentra Activa o ha Finalizado, y segun estos valores las muestra en una zona u otra: + +![](imagenes/02-panel-activa-finalizada.png) + +### Encuestas Finalizadas + +Unicamente se pueden ver los resultados de la votación, pero no se puede votar en ella. + +![](imagenes/05-votos-finalizada.png) + +### Encuestas Activas + +* Se puede participar en la encuesta y votar: + +![](imagenes/03-votar.png) + +* Se puede simplemente ver los resultados sin votar: + +![](imagenes/04-votos-activo.png) + +--- + +# Imagen y Contenedor de Encuestas + + +## Construir la imagen + +El `Dockerfile` para crear la imagen es muy sencillo: + +``` +FROM python:3.11-slim +WORKDIR /app +RUN pip install --no-cache-dir flask +EXPOSE 8080 +CMD ["python", "app.py"] +``` + +La contrucción de la imagen `encuestas` es muy sencilla: + +``` +docker build -t encuestas . + +``` + +## Ejecutar el contenedor + +Para que la aplicación funcione correctamente al iniciar el contenedor vamos a realizar el montaje de 2 recursos: + +* Fichero con el código de la aplicacion: `app.py` lo vamos a montar en el contenedor en el directorio `/app/` +* Directorio de Encuestas: `./encuestas/` lo vamos a montar en el contenedor como si el directorio `/data/` + +La manera de iniciarlo desde la terminal sería: + +``` +# Detener y borrar cualquier contenedor de encuestas previo +docker rm -f encuestas 2> /dev/null + + +# Iniciar contenedor encuestas +docker run -d \ + --name encuestas \ + --restart always \ + -p 8080:8080 \ + -v ${PWD}/app.py:/app/app.py \ + -v ${PWD}/encuestas:/data \ + encuestas + +``` + +Una vez se haya iniciado el conetendor, puedes ver la aplicación web desde la URL desde donde se ejecuta o si es en modo local conectandote a: http://localhost:8080 + +Si necesitas que se inicie en otro puerto cambia en la ejecución de *docker run* la línea `-p 8080:8080` por el puerto que desees: `-p MI_PUERTO:8080` + +--- + +# Formato de los ficheros de Encuestas + +Se considera un fichero de encuestas todos los ficheros que terminen en `.encuesta` y estén dentro del directorio `encuestas` (que se montará en `/data/`) + +El formato que se utiliza es el de un fichero *INI* (muy sencillo de procesar) en que cada *Sección* (identificada por corchetes) tiene varios *campos de datos* identificados por pares `clave = valor` + +Se permite el uso de comentarios mediante `#` o `;` + +Además como luego se va a procesar y "pintar" en HTML se permite el uso de etiquetas HTML, tales como: + +* Negrita: ` ` +* Cursiva: ` ` ó ` ` +* Colores: + - Rojo: ` ... ` + - Verde: ` ... ` + - Azul: ` ... ` + +Por cada *Opción* (identificada por su NUMERO) de respuesta tiene que existir en la sección `Votos` el mismo NUMERO en el que guardar los votos. + + +El formato básico es: + +``` +[encuesta] +titulo = Titulo de la Encuesta +pregunta = Texto de la pregunta para saber qué opción prefiere +# activa = true|false +activa = true + +[opciones] +# n = texto de la opcion +1 = Texto de la opcion 1 +2 = Texto de la opcion 2 +3 = Texto de la opcion 3 +4 = Texto de la opcion 4 + +[votos] +# Inicializar con valor 0 +1 = 0 +2 = 0 +3 = 0 +4 = 0 +``` + +## Orden y Nombres de las Encuestas + +La aplicación lee de forma alfabética los ficheros `.encuesta` y utiliza ese orden para mostrar las encuestas, tanto las activas como las finalizadas. + +El nombre de los ficheros no tiene ninguna limitación, puedes escribirlos como desees siempre y cuando finalicen en `.encuesta` + +Se recomienda: + +* Uso de un Prefijo: El uso de un prefijo numérico para el renombrado de los ficheros permite forzar el orden a la hora de mostrarse vía Web. +* Letra ó Código para el Estado: Si tienes muchas encuestas, puedes incluir al nombre de fichero una letra o un identificador para saber si una encuesta está Activa (`A`) o ha Finalizado (`F`). + +Por ejemplo: + +``` +. +├── app.py +└─── encuestas + ├── 001-A_Que_Distro_Linux_usas.encuesta + ├── 002-A_Editor_Nano-Joe-Vi-eMacs.encuesta + ├── 001-F_Distro_Linux_para_PRO.encuesta + └── 099-A_Que_IDE-Framework_usas.encuesta +``` + +--- + + + + + diff --git a/imagenes/01-panel-vacio.png b/imagenes/01-panel-vacio.png new file mode 100644 index 0000000..4a9566f Binary files /dev/null and b/imagenes/01-panel-vacio.png differ diff --git a/imagenes/02-panel-activa-finalizada.png b/imagenes/02-panel-activa-finalizada.png new file mode 100644 index 0000000..fbb7957 Binary files /dev/null and b/imagenes/02-panel-activa-finalizada.png differ diff --git a/imagenes/03-votar.png b/imagenes/03-votar.png new file mode 100644 index 0000000..b21575d Binary files /dev/null and b/imagenes/03-votar.png differ diff --git a/imagenes/04-votos-activo.png b/imagenes/04-votos-activo.png new file mode 100644 index 0000000..7b1d953 Binary files /dev/null and b/imagenes/04-votos-activo.png differ diff --git a/imagenes/05-votos-finalizada.png b/imagenes/05-votos-finalizada.png new file mode 100644 index 0000000..4d61d44 Binary files /dev/null and b/imagenes/05-votos-finalizada.png differ