Merge pull request #1 from jswelling/web_server_updates

Separate Streamlit and Flask tracks

docs/now_we_need_a_web_server_body.md

@@ -1,4 +1,4 @@
-## Now We Need A Web Server ##
+# Now We Need A Web Server ##
 
 In class, most visualization (and practically everything else!) takes
 place in Jupyter Notebooks.
@@ -17,6 +17,12 @@ The goal is to learn to produce a visualization that will be served by a
 web server, not to be able to produce the web server itself.
 
 
+We are going to use a simple, limited web server called Streamlit to set up
+a convenient tool to use when we look at node-and-edge graphs.  There is a
+separate track of the lecture describing Flask, a more general-purpose web
+server, for those interested.
+
+
 
 ## What We Will Set Up
 
@@ -38,20 +44,31 @@ people's computers, running code like your code.
 ## Streamlit and Flask
 
 There are actually two examples of web servers here, written in
-* [Flask](https://flask.palletsprojects.com/en/2.3.x/), a very pythonic, full-featured server
 * [Streamlit](https://streamlit.io/), which does much of the work for you, whether you like it or not.
+* [Flask](https://flask.palletsprojects.com/en/2.3.x/), a very pythonic, full-featured server
 
 There are others, like [Django](https://www.djangoproject.com/)) , which is a larger, more complex framework.
 Lots of web pages are now written in [React](https://react.dev/) .  Jupyter Notebook is itself partly a web server.
 
 
+I use Streamlit when I want to quickly set up an interface to show something
+simple.  It gets very awkward and slow as the interface gets more complex.
+
+Streamlit is _pretending_ the web page is written in Python, by faking little
+Javascript connections to actual running elements in the browser.  This
+illusion gets hard to maintain.  At that point, I switch to Flask or React.
+
+
 Definitely clone the class Streamlit repo, which is
 [CMU-MS-DAS-Vis-Streamlit](https://github.com/jswelling/CMU-MS-DAS-Vis-Streamlit) .  We want to run it
 today, and use it to draw GraphViz graphs.
 
 
+<!-- .slide: data-background="#cccccc" -->
 The class Flask repo is [CMU-MS-DAS-Vis-Flask](https://github.com/jswelling/CMU-MS-DAS-Vis-Flask) .  Clone
-and run it if you are interested; it will be used in class for examples.
+and run it if you are interested; it may be used in class for examples.
+
+(This color means this is the Flask track)
 
 
 
@@ -60,24 +77,27 @@ and run it if you are interested; it will be used in class for examples.
 ```
 git clone https://github.com/jswelling/CMU-MS-DAS-Vis-Streamlit
 cd CMU-MS-DAS-Vis-Streamlit
-conda create -n streamlitEnv python=3.10 pip
+conda create -n streamlitEnv python=3.11 pip
 source activate streamlitEnv
 pip install -r requirements.txt
 ```
+We are ready to run the server but have not yet started it.
 
 
+<!-- .slide: data-background="#cccccc" -->
 ## Flask Installation Steps (for Linux)
 
 ```
 git clone https://github.com/jswelling/CMU-MS-DAS-Vis-Flask
 cd CMU-MS-DAS-Vis-Flask
-conda create -n flaskEnv python=3.10 pip
+conda create -n flaskEnv python=3.11 pip
 source activate flaskEnv
 pip install -r requirements.txt
 git checkout d3_support  # to get all the features
 bash init_db.sh
 bash run_app.sh
 ```
+We have built and initialized the server, and started it up.
 
 
 
@@ -88,25 +108,35 @@ all the parts are visible.
 ![Our simple Flask application](images/Simple_Flask_Application.svg)
 
 
+Streamlit makes this appear simple- it looks like your python code is
+"running in" your Browser.  But it's not- Streamlit is faking the whole
+thing by creating Javascript tools in the browser and connecting to them
+from python functions.
+
+All the functionality is the same.
+
+
 You are running the server on your own local machine, and it should
 not be visible from any other machine.  It is in developer mode and
 has almost no security.  **Never run this server in public unless you
 have fixed the security issues.**
 
 
 Unfortunately the details of the security issues are beyond the scope
-of this course.  Flask, having a real SECRET_KEY is necessary.  One must
-guarding against false inputs (SQL injection).  
+of this course.  For Flask, having a real SECRET_KEY is necessary.  One must
+guarding against false inputs (SQL injection).
+
+Streamlit takes some steps to protect you, behind the scenes.
 
 
 ## A More Complete Environment
 
 ![A more complete Flask application](images/More_Complete_Flask_Application.svg)
 
 
-We would need a real web server, because Flask or Streamlit alone is too slow for
-real traffic.  Flask or Streamlit can then run in a Python environment within that
-webserver.
+We would need a real web server, because Streamlit or Flask alone is too
+slow for real traffic.  Streamlit or Flask can then run in a Python
+environment within that webserver.
 * [Apache](https://httpd.apache.org/)
 * [NGINX](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/)
 
@@ -115,23 +145,30 @@ We would need https support.  A real web server would provide that,
 and automatically translate to the http which our server speaks.
 
 
-We would need a real database. We have a tiny one based on Sqlite, but
+We would need a real database. The Flask example uses a tiny one
+based on Sqlite, but
 for a serious project we would want a full-sized SQL database like:
 * [MySQL](https://www.mysql.com/)
 * [PostgreSQL](https://www.postgresql.org/)
 
+(Streamlit is hiding the database from you)
+
 
 We would need session management.
-* In Flask: There is really no state to the sessions we have now; the visualization is completely recreated every
-  time we click 'Submit'.  A real session would allow things to be
-  remembered between page views.  Flask has plug-ins for that.
 * In Streamlit: The model is that the Python program completely re-runs every time the page gets updated.  One has
   to manage session state by using st.session_state .  It gets awkward.
 
 
+<!-- .slide: data-background="#cccccc" -->
+* In Flask: There is really no state to the sessions we have now;
+  the visualization is completely recreated every
+  time we click 'Submit'.  A real session would allow things to be
+  remembered between page views.  Flask has plug-ins for that.
+
+
 We would need better login management.  Users should provide email
-addresses and those should be verified, for example.  Flask and
-Steamlit both have plug-ins to help with this.
+addresses and those should be verified, for example.  Streamlit and
+Flask both have plug-ins to help with this.
 
 
 
@@ -141,7 +178,7 @@ There are actually two separate web servers here:
 * _curveserver.py_ , the current demo
 * _graphserver.py_ , for GraphViz later
 
-Streamlit can only handle one-page websites, so they have to be separate.
+Streamlit is only simple for one-page websites, so they have to be separate.
 
 
 ## Start up the curveserver:
@@ -151,8 +188,8 @@ cd src/webserver
 conda activate streamlitEnv
 streamlit run curveserver.py
 ```
-That's it; streamlit does the rest!  Now open http://localhost:8501/ and
-you should see your web page.
+That's it; streamlit does the rest!  Now got to a browser and
+open http://localhost:8501/ and you should see your web page.
 
 
 ## The code is really simple.
@@ -188,6 +225,7 @@ This bit grabs the image back from the Figure as SVG and sends it to the page:
 
 
 
+<!-- .slide: data-background="#cccccc" -->
 ## Exploring The Flask Version
 
 The application follows this [Flask Tutorial](https://flask.palletsprojects.com/en/2.0.x/tutorial/) very closely, except that:
@@ -199,6 +237,7 @@ The application follows this [Flask Tutorial](https://flask.palletsprojects.com/
   by *main.py* and *index.html*
 
 
+<!-- .slide: data-background="#cccccc" -->
 The stuff in ```{{ }}``` and etc. is
 [jinja templating](https://jinja.palletsprojects.com/en/3.0.x/).  Remember
 that it is evaluated *at the server*, using information provided in
@@ -208,11 +247,13 @@ You can see the rendered version in the Developer Tools source view.  By the
 time it reaches the web browser, it has been converted to standard HTML.
 
 
+<!-- .slide: data-background="#cccccc" -->
 It is jinja templating that lets us implement a 'standard' page using the
 *base.html* template.  This functionality is very flexible and could be
 expanded *a lot*, but for now let's keep it fairly simple.
 
 
+<!-- .slide: data-background="#cccccc" -->
 The stuff in the ```<script>...</script>``` blocks is javascript.  We use
 one standard javascript library, [jQuery](https://jquery.com/) , for
 convenience.  There is also some custom javascript to handle some individual
@@ -225,6 +266,7 @@ $("#somename")
 to find and access an HTML element with the id string "somename".
 
 
+<!-- .slide: data-background="#cccccc" -->
 Javascript code actually executes in the browser, and controls all behavior
 beyond just displaying standard HTML.  For example, it is javascript code
 that allows us to use the