From fc0b4654e6134932c08328869ed36b2bc704be3f Mon Sep 17 00:00:00 2001
From: Eesaan Atluri <atlurie@uab.edu>
Date: Fri, 31 Aug 2018 14:32:51 -0500
Subject: [PATCH] Walkthrough steps for installing Jupyter on OOD.
---
jupyter_install.md | 140 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 140 insertions(+)
diff --git a/jupyter_install.md b/jupyter_install.md
index e69de29..55d38bf 100644
--- a/jupyter_install.md
+++ b/jupyter_install.md
@@ -0,0 +1,140 @@
+# Installing Jupyter in dev-cluster
+This tutorial will walk you through creating an interactive Jupyter app that your users will use to launch a Jupyter Notebook Server within a batch job on a compute node. The user will then be able to connect to the running server through their browser and take advantage of the resources provided within the batch job.
+
+Make sure to follow the setup instructions to enable interactive apps in Open On Demand
+
+
+### 1. Software Requirements
+The Jupyter app requires the following software to be installed on the compute nodes that that batch job is meant to run on, NOT the OnDemand node:
+
+- Jupyter Notebook 4.2.3+ (earlier versions are untested by may work for you)
+ - Install jupyterhub via easybuild through which you can run the Jupyter notebook server.
+ ```
+ eb -S jupyter
+ eb jupyterhub-0.8.1-foss-2017a-Python-3.6.4.eb -r
+ ```
+- OpenSSL 1.0.1+ (used to hash the Jupyter Notebook server password)
+- Lmod 6.0.1+ or any other CLI tool used to load appropriate environments within the batch job before launching the Jupyter Notebook Server.
+(Lmod should already be installed in compute node.)
+
+### 2. Copy Jupyter App
+- We do all of our app development in our Open OnDemand sandbox directory. So
+ we first need to create our sandbox directory:
+
+ `$ mkdir -p "${HOME}/ondemand/dev"`
+
+
+>Open OnDemand looks for apps in *special* directories on the file system.
+ Two types of apps in particular are _system_ apps and _sandbox_ apps.
+>
+ system apps
+ These are apps that all users have access to and appear in the
+ Dashboard dropdown menus. They are installed on the local disk with
+ very permissive file permissions.
+ Located on the file system under::
+ /var/www/ood/apps/sys/<app_directory>
+>
+ This system app can be accessed by navigating in your browser to::
+>
+ https://ondemand.my_center.edu/pun/sys/<app_directory>
+>
+ If this is a system Interactive App (Dashboard plugin), then it can be
+ accessed by navigating to::
+>
+ https://ondemand.my_center.edu/pun/sys/dashboard/batch_connect/sys/<app_directory>/session_contexts/new
+
+>
+ sandbox apps
+ These are apps that **only** the owner of the app can access
+ irrespective of file permissions. Typically you develop apps in your
+ sandbox before moving them to the production system location.
+>
+ Located on the file system under::
+>
+ ${HOME}/ondemand/dev/<app_directory>
+>
+ Can be accessed by navigating in your browser to::
+>
+ https://ondemand.my_center.edu/pun/dev/<app_directory>
+>
+ Note that we just replaced ``sys`` with ``dev`` in the URL when going
+ from system app to sandbox app.
+>
+ If this is a sandbox Interactive App (Dashboard plugin), then it can be
+ accessed by navigating to::
+>
+ https://ondemand.my_center.edu/pun/sys/dashboard/batch_connect/dev/<app_directory>/session_contexts/new
+>
+ Notice that we are using the **system** :ref:`dashboard` to launch the
+ **sandbox** Interactive App (Dashboard plugin).
+
+- After creating the sandbox directory navigate in your browser to: https://ondemand.my_center.edu/
+
+
+ You should now see a *Develop* dropdown menu option in the top right of the
+ `dashboard`.
+
+- Open up the *Develop* menu dropdown and click the link *My Sandbox Apps
+ (Development)*.
+
+- You will navigate to a page that lists all of your sandbox apps (all the
+ apps in your sandbox directory). For now click *New App* in the top left
+ of the page.
+
+- Currently there is only one option for building new apps and that is to
+ "Clone an existing app". Click the button *Clone Existing App*.
+
+- Now we are presented with a form that describes how we will clone the app.
+
+ Directory name
+ this is the directory that the app will be cloned to in our sandbox
+ directory (must be unique)
+ Git remote
+ this is the link to the git repo that is cloned
+ Create a new Git Project from this?
+ whether we want to create a new app from this git repo
+
+ For now fill in the form with the following values:
+
+ Directory name
+ ``jupyter``
+ Git remote
+ ``https://github.com/OSC/bc_example_jupyter.git``
+ Create a new Git Project from this?
+ check this!
+
+### 3. Customize Attributes
+
+The form.yml file (User Form) located in the root of the app is for defining the attributes (their values or HTML form elements) used when generating the batch script.
+
+- We will begin by adding a cluster for the Jupyter app to use. You do this by editing the form.yml file.
+
+ `vim /var/www/ood/apps/sys/jupyter/form.yml`
+
+ replace `my_cluster` with a valid cluster that corresponds to a cluster configuration file located under `/etc/ood/config/clusters.d/my_cluster.yml`.
+
+- We will also edit the module(s) that is(are) required to be loaded within our batch job to get a Jupyter Notebook Server running:
+
+ `vim /var/www/ood/apps/sys/jupyter/form.yml`
+
+ Add `jupyterhub` to the modules section in addition to `python`.
+
+- Click on `Interactive Apps` dropdown in the dashboard.
+ - click on `Jupyter Notebook` listed under servers tab
+
+- You should see a web form for the Jupyter app. Fill in the form now and try to Launch a Jupyter batch job.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
--
GitLab