Skip to content
Snippets Groups Projects
Commit 2a0179c4 authored by William Bell's avatar William Bell
Browse files

Updating documentation to address SSL certificate issue and move to newer Python package versions

parent 16c1716b
No related branches found
No related tags found
No related merge requests found
No preview for this file type
......@@ -10,6 +10,7 @@
\usepackage{babel}
\usepackage{lastpage}
\usepackage[T1]{fontenc}
\usepackage{csvsimple}
%--------------------------------
% Line separation.
......@@ -131,22 +132,38 @@ If these exercises are followed using an Azure student account, then a MariaDB d
\begin{enumerate}
\item Follow the instructions at \href{https://docs.microsoft.com/en-us/azure/mysql/howto-configure-ssl}{https://docs.microsoft.com/en-us/azure/mysql/howto-configure-ssl} to download the \texttt{BaltimoreCyberTrustRoot.crt.pem} file and save it into the \texttt{src} directory.
\item Open a command prompt or Bash shell window in the \texttt{src} directory. Then connect to the remote MariaDB database server using the command given in Listing~\ref{listing:mysql-connect}. If this command is typed into a Bash shell on Windows, then it must be prefixed by \texttt{winpty}. This prefix is not needed when the client command is used with a Windows command prompt or a Bash shell on Linux or OSX. Using the teaching environment:
\item Set the environment variables for either the student account or teaching environment:
\begin{itemize}
\item \texttt{db\_server} - The full database server name, ending in \texttt{.mariadb.database.azure.com}.
\item \texttt{db\_user} - The MariaDB user name issued.
\item \texttt{db\_password} - The MariaDB password issued.
\item \texttt{db\_name} - The \texttt{db\_user}, when using the teaching environment.
\item \texttt{DB\_SERVER} - The full database server name, ending in \texttt{.mariadb.database.azure.com}.
\item \texttt{DB\_USER} - The MariaDB user name.
\item \texttt{DB\_PASSWORD} - The MariaDB password.
\item \texttt{DB\_NAME} - The database name. (This is the same as the \texttt{DB\_USER}, when using the teaching environment.)
\end{itemize}
\item Open a command prompt or Bash shell window in the \texttt{src} directory. Then connect to the remote MariaDB database server using the command given in Listing~\ref{listing:mysql-connect} or \ref{listing:mysql-connect-ssl}, where Listing~\ref{listing:mysql-connect-ssl} should be used if the \texttt{BaltimoreCyberTrustRoot.crt.pem} certificate has already been installed on the host operating system. If this command is typed into a Bash shell on Windows, then it must be prefixed by \texttt{winpty}.
\clearpage
\begin{lstlisting}[caption={Connecting to the remote MariaDB server.},label=listing:mysql-connect,numbers=none,language=,showspaces=true]
mysql --host $db_server \
--user $db_user -p$db_password --ssl \
mysql --host $DB_SERVER \
--user $DB_USER -p$DB_PASSWORD --ssl \
--ssl-verify-server-cert --ssl-ca=BaltimoreCyberTrustRoot.crt.pem \
--tls-version="TLSv1.2,TLSv1.3" $db_name
--tls-version="TLSv1.2,TLSv1.3" $DB_NAME
\end{lstlisting}
\begin{lstlisting}[caption={Connecting to the remote MariaDB server.},label=listing:mysql-connect-ssl,numbers=none,language=,showspaces=true]
mysql --host $DB_SERVER \
--user $DB_USER -p$DB_PASSWORD --ssl \
--tls-version="TLSv1.2,TLSv1.3" $DB_NAME
\end{lstlisting}
If the command given in Listing~\ref{listing:mysql-connect} fails with the error that is given in Listing~\ref{listing:ssl-error}, run the command that is given in Listing~\ref{listing:mysql-connect-ssl} instead. This error can occur if the \texttt{BaltimoreCyberTrustRoot.crt.pem} is already installed on the host computer, such that it clashes with the version provided locally.
\begin{lstlisting}[caption={Certificate chain error.},label=listing:ssl-error,numbers=none,language=,showspaces=true]
ERROR 2026 (HY000): SSL connection error: Server certificate validation failed. A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider.
\end{lstlisting}
\item Check the tables present and remove any existing tables by using Listing~\ref{listing:list-tables} and \ref{listing:db-reset}, respectively. The Listing~\ref{listing:db-reset} assumes that the teaching environment is being used.
\item Check the tables present and remove any existing tables by using Listing~\ref{listing:list-tables} and \ref{listing:db-reset}, respectively. The name \texttt{db\_name} should be replaced with the database name.
\begin{lstlisting}[caption={Listing the tables and columns.},label=listing:list-tables,numbers=none,language=,showspaces=true]
SHOW TABLES;
......@@ -154,8 +171,8 @@ SHOW COLUMNS IN book;
\end{lstlisting}
\begin{lstlisting}[caption={Creating an empty database, where \texttt{db\_user} should be replaced by the database user name.},label=listing:db-reset,numbers=none,language=,showspaces=true]
DROP DATABASE IF EXISTS db_user;
CREATE DATABASE db_user;
DROP DATABASE IF EXISTS db_name;
CREATE DATABASE db_name;
\end{lstlisting}
\end{enumerate}
......@@ -164,9 +181,23 @@ CREATE DATABASE db_user;
It is easier to debug a program when it is running on the local computer, since the log messages may be clearer, the edit and update loop is quicker and a debugger can be used.
\begin{enumerate}
\item Set the environment variables.
\item Run the web service on the local computer, using the Azure MariaDB database.
\item Verify the end points work as expected by using Listing~\ref{listing:web-service-test}.
\item Use Visual Studio Code to open the \texttt{azure-stateful-webapp/src} folder.
\item Open the \texttt{app.py} file.
\item Run the file \texttt{app.py}. This will fail, since there is no local database server.
\item Set the environment variables within the \texttt{TERMINAL} window:
\begin{itemize}
\item \texttt{DB\_SERVER} is the full name of the remote database server, ending in ``mariadb.database.azure.com'' without the quotations.
\item \texttt{DB\_USER} is the user name for the remote database server.
\item \texttt{DB\_PASSWORD} is the password for the remote database server.
\item \texttt{DB\_NAME} is the name of the database within the remote database server.
\item \texttt{DB\_SSL} is set to \texttt{"true"}, if the \texttt{BaltimoreCyberTrustRoot.crt.pem} is already installed on the host operating system.
\item \texttt{DB\_SSL\_CERT} is set to \texttt{BaltimoreCyberTrustRoot.crt.pem}, if the \texttt{BaltimoreCyberTrustRoot.crt.pem} is not installed on the host operating system.
\end{itemize}
Either \texttt{DB\_SSL} or \texttt{DB\_SSL\_CERT} should be set, but not both.
\item Run the file \texttt{app.py}.
\item Verify the end points work as expected by using Listing~\ref{listing:web-service-test} or Postman.
\begin{lstlisting}[caption={Testing the web service.},label=listing:web-service-test,numbers=none,language=,showspaces=true]
curl -s -X GET "http://127.0.0.1:5000/books/"
......@@ -176,7 +207,7 @@ curl -s -X POST -H "Content-Type: application/json" \
curl -s -X GET "http://127.0.0.1:5000/books/"
\end{lstlisting}
\item Stop the web service.
\item Stop the web service by typing \texttt{ctrl-c} in the TERMINAL window.
\item Verify the database table structure using the MariaDB client and Listing~\ref{listing:list-tables}.
\end{enumerate}
......@@ -190,20 +221,22 @@ zip -r myapp.zip app.py models.py routes.py requirements.txt \
startup.txt BaltimoreCyberTrustRoot.crt.pem
\end{lstlisting}
\item Create a Web App by using Listing~\ref{listing:create-web-app}.
\item Create a Web App by using Listing~\ref{listing:create-web-app}, where the \texttt{plan\_id} should be replaced with the id of the existing plan on the teaching environment. Alternatively, a plan can be created in the student account. Following the Azure resource naming convention, the \texttt{app\_name} should start with the prefix ``app-''.
\begin{lstlisting}[caption={Creating a Web App.},label=listing:create-web-app,numbers=none,language=,showspaces=true]
az webapp create --name $app_name --resource-group $resource_group \
--plan $plan_name --runtime "python|3.9" \
az webapp create --name $app_name \
--plan $plan_id \
--resource-group $resource_group \
--runtime "python|3.9" \
--startup-file startup.txt
\end{lstlisting}
\item Configure the Web App by using Listing~\ref{listing:web-app-config}.
\item Configure the Web App by using Listing~\ref{listing:web-app-config}. The DB\_SSL\_CERT setting is needed, since the Linux App Service Plan does not contain the \texttt{BaltimoreCyberTrustRoot.crt.pem} certificate.
\begin{lstlisting}[caption={Configuring the Web App, with the database connection details and build flag.},label=listing:web-app-config,numbers=none,language=,showspaces=true]
az webapp config appsettings set --resource-group $resource_group \
--name $app_name --settings DB_SERVER=$db_server DB_NAME=$db_name \
DB_USER=$db_user DB_PASSWORD=$db_password \
--name $app_name --settings DB_SERVER=$DB_SERVER DB_NAME=$DB_NAME \
DB_USER=$DB_USER DB_PASSWORD=$DB_PASSWORD \
DB_SSL_CERT=BaltimoreCyberTrustRoot.crt.pem \
SCM_DO_BUILD_DURING_DEPLOYMENT=true
\end{lstlisting}
......@@ -240,5 +273,9 @@ az webapp delete --name $app_name --resource-group $resource_group
\item Remove the database tables using the MariaDB client and Listing~\ref{listing:db-reset}.
\end{enumerate}
\clearpage
\input{software-versions}
\end{document}
\ No newline at end of file
......@@ -3,6 +3,6 @@ MariaDB Client,Native,10.5.10
Python,Native,3.9.7
azure-cli,Native,2.45.0
Flask,Python,2.2.3
Flask-SQLAlchemy,3.0.3
Flask-SQLAlchemy,Python,3.0.3
mariadb,Python,1.0.11
SQLAlchemy,Python,2.0.4
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment