Skip to content

Commit 9d53f47

Browse files
dpuenteramirezdpuenteramirez
committed
Written all UBUMLaaS Programmer's Manual excepto for testing #159 
1 parent f19bb71 commit 9d53f47

File tree

3 files changed

+202
-9
lines changed

3 files changed

+202
-9
lines changed

‎docs/anexos.pdf‎

20.8 KB
Binary file not shown.

‎docs/bibliografiaAnexos.bib‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,4 +217,8 @@ @misc{gitkraken
217217

218218
@misc{VSCode, title={Visual Studio Code}, url= {https://code.visualstudio.com/}}
219219

220-
@misc{PyCharm, title={PyCharm}, url= {https://www.jetbrains.com/pycharm/}}
220+
@misc{PyCharm, title={PyCharm}, url= {https://www.jetbrains.com/pycharm/}}
221+
222+
@misc{VSCode-Remote-SSH, title={Remote SSH}, url={https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh}}
223+
224+
@misc{Remote-Development-Tricks-Tips, title={Remote Development Tips and Tricks}, url={https://code.visualstudio.com/docs/remote/troubleshooting#_installing-a-supported-ssh-client}, year={2022}, author={Microsoft}}

‎docs/tex/D_Manual_programador.tex‎

Lines changed: 197 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,203 @@ \subsection{Estructura de directorios}
4545
\end{itemize}
4646

4747
\subsection{Manual del programador}
48+
En esta subsección se describen todos aquellos recursos seguidos por el equipo de desarrollo para, valga la redundancia, desarrollar el proyecto. De tal forma que un futuro desarrollador/mantenedor del proyecto no tenga inconvenientes a la hora de retomar el proyecto y conocerlo.
49+
50+
\subsubsection{Entorno de desarrollo}
51+
Para poder continuar con el desarrollo del proyecto, se requiere tener instalado el siguiente \textit{software} en el equipo:
52+
\begin{itemize}
53+
\tightlist
54+
\item Python 3.7+.
55+
\item Bibliotecas Python.
56+
\item Git
57+
\item VSCode
58+
\end{itemize}
59+
60+
En los siguientes apartados se detalla la instalación de cada uno de los componentes anteriormente citados.
61+
62+
\subsubsection{Python 3.7+}
63+
Al comienzo del proyecto, muchas de sus funcionalidades eran compatibles con Python 2, pero el nuevo desarrollo ha utilizado indistintamente métodos existentes en versiones anteriores de Python y algunos que se han introducido a partir de la version 3.7, disponible desde~\cite{pythonGetIt}. Es importante que los binarios se encuentren en el \texttt{path} del sistema para que no de problemas de ejecución.
64+
65+
\subsubsection{Bibliotecas Python}
66+
A continuación (ver Tabla~\ref{tab:bibliotecas-python-ubumlaas}), se van a detallar uno de los puntos más importantes para poder <<hacer funcionar>> el proyecto, puesto que se van a necesitar versiones concretas de determinadas librerías para que todo se integre correctamente con todo y se pueda ver y utilizar como un sistema homogéneo.
67+
68+
\begin{table}[H]
69+
\centering
70+
\begin{tabular}{c|c}
71+
Biblioteca & Versión \\
72+
\toprule
73+
\rowcolor[HTML]{EFEFEF}
74+
flask & 1.1.1 \\ \midrule
75+
werkzeug & 0.15.6 \\ \midrule \rowcolor[HTML]{EFEFEF}
76+
flask-login & 0.4.1 \\ \midrule
77+
flask-wtf & 0.14.2 \\ \midrule \rowcolor[HTML]{EFEFEF}
78+
flask-sqlalchemy & 2.4.0 \\ \midrule
79+
flask-redis & 0.4.0 \\ \midrule \rowcolor[HTML]{EFEFEF}
80+
rq & 1.1.0 \\ \midrule
81+
scikit-learn & 0.24 \\ \midrule \rowcolor[HTML]{EFEFEF}
82+
pandas & 0.25.1 \\ \midrule
83+
urllib3 & 1.25.6 \\ \midrule \rowcolor[HTML]{EFEFEF}
84+
requests & 2.22.0 \\ \midrule
85+
future & 0.16.0 \\ \midrule \rowcolor[HTML]{EFEFEF}
86+
whichcraft & 0.4.1 \\ \midrule
87+
pytest & 5.2.1 \\ \midrule \rowcolor[HTML]{EFEFEF}
88+
selenium & 3.141.0 \\ \midrule
89+
imbalanced-learn & 0.5.0 \\ \midrule \rowcolor[HTML]{EFEFEF}
90+
itsdangerous & 1.1.0 \\ \midrule
91+
flask-mail & 0.9.1 \\ \midrule \rowcolor[HTML]{EFEFEF}
92+
pycountry & 22.3.5\\ \midrule
93+
geopy & 2.2.0\\ \midrule \rowcolor[HTML]{EFEFEF}
94+
psutil & 5.9.0\\ \midrule
95+
glances & 3.2.4.2\\ \midrule \rowcolor[HTML]{EFEFEF}
96+
flask-migrate & 2.5.2 \\ \midrule
97+
python-weka-wrapper3 & 0.1.7 \\ \midrule \rowcolor[HTML]{EFEFEF}
98+
liac-arff & 2.2.1 \\ \midrule
99+
email-validator & 1.1.1 \\ \midrule \rowcolor[HTML]{EFEFEF}
100+
\bottomrule
101+
\end{tabular}
102+
\caption{Bibliotecas utilizadas y sus versiones.}\label{tab:bibliotecas-python-ubumlaas}
103+
\end{table}
104+
105+
Las versiones indicadas en la tabla~\ref{tab:bibliotecas-python-ubumlaas} son las que se han utilizado para el desarrollo del proyecto, se pueden actualizar a versiones futuras, siempre y cuando sean compatibles entre sí.
106+
107+
\subsubsection{Git}
108+
\imagenRuta{../img/anexos/manual-programador/gitkraken}{Interfaz de \texttt{GitKraken}.}{gitkraken}
109+
Para poder utilizar el repositorio ha de utilizarse el gestor de versiones \texttt{Git}. Se recomienda utilizar GUI con soporte a VC\footnote{Control de versiones (\textit{Version Control}).} tales que no requieran de una interfaz de comandos para su utilización, pero eso se deja a decisión del futuro desarrollador.
110+
111+
En la Figura~\ref{fig:gitkraken} se aprecia como el \textit{software} \texttt{GitKraken} permite, de forma intuitiva y sencilla, el uso de \texttt{Git} y todo su potencial. Se puede obtener desde~\cite{gitkraken}.
112+
113+
El repositorio posee una serie diferente de ramas de trabajo, se recomienda para producción utilizar o el último \textit{release} o bien la rama principal.
114+
115+
\subsubsection{Visual Studio Code}
116+
\texttt{Visual Studio Code} es una herramienta de amplia versatilidad la cual soporta todos los lenguajes de programación utilizados en este proyecto (y muchos más) de forma nativa; además, posee ciertos \textit{plugins} que facilitan el desarrollo proporcionando \textit{snippets} y similares. Se recomienda su uso ya que es un IDE <<todo-en-uno>>, facilitando las tareas de desarrollo.
117+
118+
Se puede obtener desde~\cite{VSCode}.
48119

49120
\subsection{Compilación, instalación y ejecución del proyecto}
121+
En esta subsección se va a detallar el proceso a seguir para poder hacer uso del proyecto en local, modificarlo y/o utilizarlo. La forma de desarrollo del proyecto no ha sido estrictamente en local, sino que el proyecto se encontraba alojado en un equipo servidor y mediante SSH\footnote{\textit{Suite} de protocolos los cuales especifican estándares para operar los servicios de red de forma segura entre anfitriones para los que no existe una relación de confianza a través de redes no seguras. Las comunicaciones entre pares se encuentran encriptadas.} se realizaba la conexión y posterior edición de los ficheros.
122+
123+
\subsubsection{Adquisición del código fuente}
124+
Lo primero que se necesita es obtener el código en el equipo, para ello podemos seguir una de las siguientes aproximaciones:
125+
\begin{itemize}
126+
\item Mediante el uso de la terminal.
127+
\begin{enumerate}
128+
\tightlist
129+
\item Apertura de la terminal.
130+
\item Desplazarse al directorio en donde se desee clonar el repositorio (usando \texttt{cd} en Unix o \texttt{dir} en Windows).
131+
\item Hacer uso del siguiente comando:\\
132+
\texttt{git clone https://github.com/dpr1005/UBUMLaaS.git}
133+
\item Se dispone de una copia idéntica a la alojada en el repositorio de \texttt{GitHub}.
134+
\end{enumerate}
135+
136+
\item Descarga desde el navegador.
137+
\begin{itemize}
138+
\tightlist
139+
\item Apertura del navegador preferido.
140+
\item Introducir en la barra de búsqueda la siguiente dirección:\\
141+
\texttt{https://github.com/dpr1005/UBUMLaaS/archive/refs/\\heads/master.zip}
142+
\item Aceptar la descarga en caso de tener habilitada la comprobación.
143+
\item Navegar con el Explorador de archivos del sistema hasta el directorio de descarga.
144+
\end{itemize}
145+
146+
\item Uso de \texttt{GitKraken}.
147+
\begin{itemize}
148+
\tightlist
149+
\item Apertura de la aplicación.
150+
\item Hacer \textit{click} en \textit{Clone a repo}.
151+
\item En \textit{Repository Management} $\rightarrow$ \textit{Clone} $\rightarrow$ \textit{Clone with URL}:
152+
\begin{itemize}
153+
\item Indicar la ruta local en la que nos interesa que se clone el repositorio.
154+
\item En URL introducir:\\
155+
\texttt{git clone https://github.com/dpr1005/UBUMLaaS.git}
156+
\end{itemize}
157+
\item Hacer \textit{click} en \textit{Clone the repo!}.
158+
\end{itemize}
159+
\end{itemize}
160+
161+
\subsubsection{Importar el proyecto en Visual Studio Code}
162+
Se diferencian dos aproximaciones, local o como se ha operado, conexión mediante SSH.
163+
164+
\begin{itemize}
165+
\item Importar el proyecto en la propia máquina donde se va a desplegar y será en ella en la que se edite.
166+
\begin{enumerate}
167+
\item Apertura de \texttt{Visual Studio Code}.
168+
\item Hacer \textit{click} en Abrir.
169+
\item Seleccionar el directorio raíz dónde lo hayamos alojado.
170+
\end{enumerate}
171+
\item Importar el proyecto en una máquina y editarlo desde otra.
172+
\begin{enumerate}
173+
\item Seguir los pasos de la adquisición del código en la máquina en la que se va a alojar el código. En el equipo local no va a estar.
174+
\item Apertura de \texttt{Visual Studio Code}
175+
\item Navegar a las Extensiones e instalar \texttt{Remote - SSH}, disponible desde~\cite{VSCode-Remote-SSH}.
176+
\item Instalar un cliente SSH compatible con \texttt{OpenSSH}. Ver guía~\cite{Remote-Development-Tricks-Tips}.
177+
\item Con todo instalado, se realiza la conexión a la máquina remota.
178+
\begin{enumerate}
179+
\item Presionar \texttt{F1} y correr el comando: \texttt{Remote-SSH: Open SSH Host...}
180+
\item Introducir el usuario y el \texttt{host/IP} en el formato:\\
181+
\texttt{user@host-o-ip} ó \texttt{user@domain@host-o-ip}
182+
\item En caso de que se solicite, introducir la contraseña, pero se recomienda configurar el uso de llaves SSH, ver guía~\cite{Remote-Development-Tricks-Tips}.
183+
\item Después de la conexión usar Archivo $\rightarrow$ Abrir carpeta, para abrir el directorio donde se encuentra el proyecto en la máquina remota.
184+
\end{enumerate}
185+
\item Todos los cambios que se realicen, se harán sobre el código en la máquina remota, la máquina local no hará más que el efecto de editor.
186+
\end{enumerate}
187+
\end{itemize}
188+
189+
\subsubsection{Crear entorno virtual de trabajo}
190+
Para poder trabajar con este proyecto (independientemente de si es para desarrollo o producción) hacen falta una serie de bibliotecas concretas de Python, las cuales, como es lógico, deben estar en la máquina en la que se va a correr; dicho con otras palabras, en la que está el código. El proyecto está preparado para crear un entorno de \texttt{Conda} propio, de forma que no interfiera con otros proyectos y sea más sencillo de mantener y actualizar.
191+
192+
Se recomienda que los binarios de anaconda o miniconda estén configurados en el \texttt{path} del sistema para poder utilizar el comando \texttt{conda} desde la línea de comandos.
193+
194+
El proceso de creación del entrono virtual con \texttt{Conda} es el siguiente:
195+
\begin{enumerate}
196+
\tightlist
197+
\item Apertura de la terminal.
198+
\item Navegar hasta la raíz del proyecto.
199+
\item Crear el entorno con:\\
200+
\texttt{conda env create -f UBUMLaaS\_env.yml}
201+
\item Cuando se desee utilizar se debe activar:\\
202+
\texttt{conda activate UBUMLaaS}
203+
\end{enumerate}
204+
205+
También se puede utilizar el procedimiento habitual para importar las bibliotecas al actual \texttt{venv} de la sesión de la terminal, pero se desaconseja su uso ya que un entorno <<genérico>> antes o después se actualizará por otros proyectos, pudiendo generar incompatibilidades con el proyecto UBUMLaaS.
206+
207+
\subsubsection{Instalación en Linux}
208+
Con los anteriores pasos realizados, la importación del proyecto y la activación del entorno virtual, se deben modificar una serie de ficheros con el fin de habilitar todas las funcionalidades que ofrece el proyecto.
209+
210+
Se deben seguir los siguientes pasos:
211+
\begin{enumerate}
212+
\item Modificar \texttt{env\_variables.sh} con los valores correctos para cada uno de los campos:
213+
\begin{lstlisting}[language=bash]
214+
export SECRET_KEY=<app secret key>
215+
export EMAIL_AC=<email>
216+
export EMAIL_PASS=<email-password>
217+
export EMAIL_URL=<email-url>
218+
export FLASK_ENV=development #development or production
219+
LIBFOLDER=/absolute/path/to/UBUMLaaS
220+
\end{lstlisting}
221+
\item Dentro del entorno virtual de UBUMLaaS en \texttt{Conda}, se debe ejecutar el siguiente comando para permitir la importación de las variables anteriormente declaradas al entorno virtual.\\
222+
\texttt{source env\_vars\_to\_conda.sh}
223+
\item Creación de la base de datos.\\
224+
\texttt{mv data\_base.sqlite ubumlaas/data.sqlite}\\
225+
* En caso de poseer una base de datos con la configuración correcta, se puede poner en \texttt{./ubumlaas/} bajo el nombre de \texttt{data.sqlite}.
226+
\item En caso de no tener instalado y configurado \texttt{Redis-Server}, ejecutar:
227+
\begin{lstlisting}[language=bash]
228+
sudo apt install redis-server
229+
sudo service redis-server start
230+
sudo systemctl enable redis-server
231+
\end{lstlisting}
232+
\end{enumerate}
233+
234+
\subsubsection{Uso del proyecto}
235+
Lo primero de todo para poder tener el producto trabajando, es desplegarlo, para ello es requisito haber completado todos los pasos previos de esta sección. Activar el entorno virtual de \texttt{Conda}, correr el lanzador, y ya está en ejecución.
236+
\begin{lstlisting}[language=bash]
237+
conda activate UBUMLaaS
238+
./run.sh
239+
\end{lstlisting}
240+
\textbf{Nota.} Es importante asegurarnos que todos los ficheros de las librerías y el lanzador del proyecto poseen permisos de ejecución necesarios (en instalaciones <<por defecto>> de Debian, CentOS, SUSE, no debería de ser necesario más que dar permisos de ejecución al lanzador).
50241

51242
\subsection{Pruebas del sistema}
52243

244+
\clearpage
53245
\section{IS-SSL}
54246

55247
\subsection{Estructura de directorios}
@@ -74,7 +266,7 @@ \subsection{Estructura de directorios}
74266
\end{itemize}
75267

76268
\subsection{Manual del programador}
77-
En esta subsección se describen todos aquellos métodos seguidos por el equipo de desarrollo para, valga la redundancia, desarrollar el proyecto. De tal forma que un futuro desarrollador no tenga inconvenientes a la hora de retomar el proyecto.
269+
En esta subsección se describen todos aquellos métodos seguidos por el equipo de desarrollo para, valga la redundancia, desarrollar el proyecto. De tal forma que un futuro desarrollador no tenga inconvenientes a la hora de retomar el proyecto.
78270

79271
\subsubsection{Entorno de desarrollo}
80272
Para poder continuar con el desarrollo del proyecto, se requiere tener instalado el siguiente \textit{software} en el equipo:
@@ -94,7 +286,7 @@ \subsubsection{Python 3.7+}
94286
\subsubsection{Bibliotecas Python}
95287
Esta sección es la más importante de todas junto con la anterior, debido a que el proyecto depende de (está construido utilizando) bibliotecas de $3^{os}$. Y en especial, determinadas versiones de las mismas.
96288

97-
En la Tabla~\ref{tab:bibliotecas-python} se detallan las bibliotecas necesarias para utilizar el proyecto tal y como se encuentra en el repositorio. Para el uso en exclusiva de las librerías de \texttt{IS-SSL} se deben utilizar aquellas que se encuentran en negrita.
289+
En la Tabla~\ref{tab:bibliotecas-python-is-ssl} se detallan las bibliotecas necesarias para utilizar el proyecto tal y como se encuentra en el repositorio. Para el uso en exclusiva de las librerías de \texttt{IS-SSL} se deben utilizar aquellas que se encuentran en negrita.
98290

99291
\begin{table}[]
100292
\centering
@@ -113,16 +305,13 @@ \subsubsection{Bibliotecas Python}
113305
\rowcolor[HTML]{EFEFEF}
114306
\bottomrule
115307
\end{tabular}
116-
\caption{Bibliotecas utilizadas y sus versiones.}\label{tab:bibliotecas-python}
308+
\caption{Bibliotecas utilizadas y sus versiones.}\label{tab:bibliotecas-python-is-ssl}
117309
\end{table}
118310

119311
Se recomienda el uso de un entorno de desarrollo de \texttt{Conda}, se facilitan ficheros de configuración tanto para \texttt{Conda} como para instalación con \texttt{PIP}.
120312

121313
\subsubsection{Git}
122-
\imagenRuta{../img/anexos/manual-programador/gitkraken}{Interfaz de \texttt{GitKraken}.}{gitkraken}
123-
Para poder utilizar el repositorio ha de utilizarse el gestor de versiones \texttt{Git}. Se recomienda utilizar GUI con soporte a VC\footnote{Control de versiones (\textit{Version Control}).} tales que no requieran de una interfaz de comandos para su utilización, pero eso se deja a decisión del futuro desarrollador.
124-
125-
En la Figura~\ref{fig:gitkraken} se aprecia como el \textit{software} \texttt{GitKraken} permite, de forma intuitiva y sencilla, el uso de \texttt{Git} y todo su potencial. Se puede obtener desde~\cite{gitkraken}.
314+
Para poder utilizar el repositorio ha de utilizarse el gestor de versiones \texttt{Git}. Se recomienda utilizar GUI con soporte a VC tales que no requieran de una interfaz de comandos para su utilización, pero eso se deja a decisión del futuro desarrollador.
126315

127316
\subsubsection{VSCode/Pycharm/\dots}
128317
El desarrollo propio del producto puede ser realizado en cualquier editor de textos, incluso en \texttt{Vi} si así se desea. La ventaja de herramientas como \texttt{Visual Studio Code} o \texttt{PyCharm}, es que permiten el uso de \textit{plugins} añadidos a los complementos del propio IDE, lo cual permite la generación de código un proceso mucho más sencillo y directo, reduciendo el número de errores ocasionados y permitiendo una depuración o refactorización del código fuente mucho más eficiente y sencilla.
@@ -170,7 +359,7 @@ \subsubsection{Adquisición del código fuente}
170359
\end{itemize}
171360
\end{itemize}
172361

173-
\subsubsection{Importar proyecto en PyCharm}
362+
\subsubsection{Importar el proyecto en PyCharm}
174363
Importar un proyecto en \texttt{PyCharm} es tan sencillo como:
175364
\begin{enumerate}
176365
\tightlist

0 commit comments

Comments
 (0)