added initial Jupyterhub page

_data/sidebars/merlin6_sidebar.yml

@@ -43,6 +43,10 @@ entries:
       url: /merlin6/slurm-examples.html
     - title: Slurm Configuration
       url: /merlin6/slurm-configuration.html
+  - title: Jupyterhub
+    folderitems:
+    - title: Jupyterhub service
+      url: /merlin6/jupyterhub.html
   - title: Announcements
     folderitems:
     - title: Downtimes

pages/merlin6/jupyterhub/jupyterhub.md

@@ -0,0 +1,81 @@
+---
+title: Jupyterhub on Merlin
+#tags:
+#keywords:
+last_updated: 12 July 2019
+#summary: ""
+sidebar: merlin6_sidebar
+permalink: /merlin6/jupyterhub.html
+---
+
+Jupyterhub provides [jupyter notebooks](https://jupyter.org/) that are launched on
+cluster nodes of merlin and can be accessed through a web portal.
+
+## Accessing Jupyterhub and launching a session
+
+The service is available inside of PSI (or through a VPN connection) at
+
+
+**<https://merlin-jupyter.psi.ch:8000>**
+
+
+   1. **Login**: You will be presented with a **Login** web page for
+      authenticating with your PSI account. We are still in a **TEST
+      PHASE** and we are using a self-generated certificate, so your
+      browser will generate a warning about it. Please agree to the
+      exception in this special case.
+   1. **Spawn job**: The **Spawner Options** page allows you to
+      specify the properties (Slurm partition, running time,...) of
+      the batch jobs that will be running your jupyter notebook. Once
+      you click on the `Spawn` button, your job will be sent to the
+      Slurm batch system. If the cluster is not currently overloaded
+      and the resources you requested are available, your job will
+      usually start within 30 seconds.
+   
+
+
+
+
+
+## JupyterLab and Classic Notebook user interfaces
+
+Your Jupyter notebook will start up with the new **JupyterLab** user interface which has a toolbar on the
+left. You can read about its features [on the official website](https://jupyterlab.readthedocs.io/en/stable/user/interface.html).
+
+However, if you prefer the classical notebook UI or you want to use some feature which has not yet been implemented in the
+new interface, you can switch to it by using the **"Launch Classic Notebook"** command from the left sidebar of JupyterLab.
+
+![launch classical notebook](/images/jupyter-launch-classic.png)
+
+## Jupyter software environments - running different kernels
+
+Your notebooks can run within different software environments which are offered by a number of available **Jupyter kernels**.
+
+E.g. in this test installation we provide two environments targeted at data science
+  * **datascience_py36**: contains Tensorflow, Keras, scikit-learn, and dependencies. Stable
+  * **keras216_py36**: also contains the Talos package. This
+    environment is experimental and subject to updates and changes.
+
+When you create a new notebook you will be asked to specify which kernel you want to use. It is also possible to switch the kernel of a running notebook, but you will lose the state of the current kernel, so you will have to recalculate the notebook cells with this new kernel.
+
+## Using nbextensions for adding features to your notebook
+
+There exist a number of useful [contributed but unofficial extensions](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/index.html)
+that make working in your notebook easier. These regrettably are not yet supported from
+within the JupyterLab UI, but you can activate them through the Classic Notebook interface (see above)
+
+ <!-- ([see above](##JupyterLab-and-Classic-Notebook-user-interfaces)) -->
+
+From the classic Notebook UI you can access the available extensions in a separate tab as displayed in this screenshot:
+
+![notebook extensions](/images/jupyter-nbextensions.png)
+
+Especially the following extensions make working with larger notebooks easier
+   * **Table of Contents**: Displays a TOC on the left and you can also configure it
+     to add and update a TOC at the head of the document.
+   * **Collapsible Headings**: allows you to fold all the cells below a heading
+
+## Troubleshooting
+
+   In case of problems or request, please either submit a **[PSI Service Now](https://psi.service-now.com/psisp)** incident containing *"Merlin Jupyterhub"* as part of the subject, or contact us by mail through <merlin-admins@lists.psi.ch> using the kind of subject line.
+