diff --git a/jupyter_install.md b/jupyter_install.md index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..55d38bf74f2b503ed0ef1f8a5e75fca3ff7d0719 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. + + + + + + + + + + + + + + +