Documentation update for Jupyter tokens. (#431)

* Documentation update for Jupyter tokens.
* Increment UW version number
* update docker jupyter config for token
* update CHANGES.md

CHANGES.md

@@ -1,6 +1,17 @@
 CHANGES: Underworld2
 =======================
 
+Release 2.8.2b [2019-10-28]
+---------------------------
+Docker:
+* Enable token authentication for Jupyter. 
+
+Documentation:
+* Update `README.md` to inform users of Jupter Authentication requirements. 
+* Update "Getting Started" page with info on how to use Authentication. 
+* Minor tweaks to documentation generator to handle static images.
+
+
 Release 2.8.1b [2019-09-02]
 ---------------------------
 Documentation:

README.md

@@ -3,6 +3,10 @@ Underworld 2
 
 ![Underworld Montage](docs/development/docs_generator/images/Montage.png)
 
+Security Update 
+---------------
+**Attention all Underworld Docker users**.  An important security update has been rolled out for all Underworld docker images. If you do not use Docker, this does not affect you. We urge all our Docker users to update their Underworld image. Image tags now refer to the updated images, so pulling `underworldcode/underworld2:2.8.1b` will replace your existing `underworldcode/underworld2:2.8.1b`. Users can therefore pull down a patched image for whichever Underworld version they are currently working with. However, as a matter of best practise, we recommend users update to the newest available Underworld image version whenever possible. Specifically, running Jupyter within Underworld containers will now require an authentication token. Please refer to the documentation pages for usage details. 
+
 
 [_Underworld 2_](http://www.underworldcode.org) is a Python API (Application Programming Interface) which provides functionality for the modelling of geodynamics processes, and is designed to work (almost) seamlessly across PC, cloud and HPC infrastructure. Primarily the API consists of a set of Python classes from which numerical geodynamics models may be constructed. The API also provides the tools required for inline analysis and data management. For scalability across multiprocessor platforms, MPI (Message Passing Interface) is leveraged, and for performant operation all heavy computations are executed within a statically typed layer. 
 

docs/development/docker/base/jupyter_notebook_config.json

@@ -1,7 +1,5 @@
 {
     "NotebookApp": {
-        "password": "",
-        "token": "",
 	"ip":"0.0.0.0"
     }
 }

docs/development/docs_generator/run-nb-to-rst.sh

@@ -2,8 +2,10 @@
 
 set -e
 mkdir -p build/user_guide
+mkdir -p build/user_guide/Figures
 cd build/user_guide
 cp ../../../../user_guide/*.ipynb .
+cp ../../../../user_guide/Figures/* Figures/.
 find . -name \*.ipynb -print0 | xargs -0 jupyter-nbconvert --to rst
 find . -name \*.ipynb -print0 | xargs -0 rm
 find . -name \*.rst   -print0 | xargs -0 python ../../switch_code_blocks.py

docs/user_guide/01_GettingStarted.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Getting started\n",
+    "# Getting Started\n",
     "\n",
     "\n",
     "## Welcome to using Underworld! \n",
@@ -53,6 +53,18 @@
     "\n",
     "If you are new to Jupyter Notebooks, you should familiarise yourself with the notebook environment first. Also, remember the **Help** menu bar option provides useful references and keyboard shortcuts.\n",
     "\n",
+    "### Jupyter Authentication\n",
+    "\n",
+    "Jupyter is, by design, a web service providing mechanisms for the execution of arbitrary code, such as your Underworld models (or other Python scripts). However, as a web service, security measures are required to preclude external parties from accessing your Jupyter instances (and thereby potentially executing malicious code). Jupyter therefore requires you to provide an authentication Token upon first accessing the service via your web browser. This token is generated when you first start Jupyter from the command line:\n",
+    "\n",
+    "![](Figures/jupyter_token.png)\n",
+    "\n",
+    "Simply copy/paste the generated token and enter it manually within your browser (once you have browsed to the Jupyter instance url, often http://127.0.0.1:8888).\n",
+    "\n",
+    "For those using the Kitematic GUI to launch our Docker image, Jupyter will be launched automatically, and the token may be found within the **CONTAINER LOGS** dialog:\n",
+    "\n",
+    "![](Figures/kitematic_token.png)\n",
+    "\n",
     "\n",
     "## How to get help\n",
     "\n",

underworld/__init__.py

@@ -59,7 +59,7 @@
 _oldflags = _sys.getdlopenflags()
 _sys.setdlopenflags( _oldflags | _ctypes.RTLD_GLOBAL )
 
-__version__ = "2.8.1b"
+__version__ = "2.8.2b"
 
 # squelch h5py/numpy future warnings
 import warnings as _warnings