#DRAFT
#Introduction
JupyterHub was developed to offer additional choices when running Jupyter Notebook servers (formerly known as IPython Notebooks). Basically, three options may be configured:
- Single user environments: one user needs one notebook to be spawned on their local or remote machine
- Temporary multiple user environments: multiple users need notebooks spawned for each user with temporary home paths
- Permanent multiple user environments: multiple users need notebooks spawned for each user with permanent home paths
Additionally, each one of the options above requires definitions for how the users are authenticated and what images are used to spawn Jupyter Notebook server containers. Those instructions can be viewed here.
This document is to guide users that are new to JupyterHub, so that they may
##Trouble shooting when setting up Developer's Environment
If you would like to run a local version of JupyterHub from the official Git repository, then you have a few options. Most of the Jupyter team members edit code with applications that aren't IDE's per se, and as such know exactly what dependencies are required to run the application. If you would rather use an IDE, however, you should consider following a few steps to ensure that the code is run correctly:
- Make sure your IDE's interpreter is set to Python 3.3+. Setup files detect if the host does not have Python 3.3 or more and will exit installation if that is not the case. However, when displaying or running the application directly from the IDE (consult specific IDE documentation on how to Run application in standard or debug mode), many errors will appear if the interpreter is set to Python 2.7.x.
- Running JupyterHub directly from your IDE won't work since it doesn't support relative paths without a full installation. Most likely you will see an error similar to:
Traceback (most recent call last):
from . import handlers, apihandlers
SystemError: Parent module '' not loaded, cannot perform relative import
To run JupyterHub directly from your source repository (useful for running and testing code without having to re install), at the root of you source files type:
$ python3 -m jupyterhub
At first, you will notice that everything is being exposed correctly to http://localhost:8000, however, opening your browser to that location will give you an empty page. (If you do so the default JupyterHub login page, then you have all CSS and JS dependencies installed correctly. JupyterHub has CSS and JS dependencies that are not identified by the IDE as such, since they are not formally imported into the source files. Therefore you need to install CSS and JS dependencies as well.
First, install bower package manager:
$ npm install -g bower
Make sure that after installation .bowerrc appears in the root of your JupyterHub repository. If you would like to run bower with sudo, use the --allow-root option. Complete bower documentation may be viewed here.
Then install lessc with npm, used for CSS and JS:
$ npm install
Finally, setup CSS and JS with Python3:
$ python3 setup.py css
$ python3 setup.py js`
You may then run JupyterHub with:
$ python3 -m jupyterhub
You now should have a working development setup and be able to write and run code without having to re install.
##Troubleshooting when running JupyterHub
###JupyterHub: To Docker or not to Docker
When running JupyterHub with Jupyter Notebook servers, one should determine whether or not to run JupyterHub within a docker container or directly on the host. By default, Jupyter Notebook servers are spawned as docker containers so considering the option of running Jupyter Notebook servers on a host or hosts is outside of the scope of this document. If considering a deployment that requires formal or informal Service Level Agreements (SLAs), it is strongly advised to test both options in order to determine what is the best course of action.
Note: the statement 'When running JupyterHub with Jupyter Notebooks...' was mentioned explicitly because, conceivably, JupyterHub could be used to spawn containers based on other docker images.
###JupyterHub troubleshooting when running Hub and Notebook servers on the same host
Regardless of whether or not you run JupyterHub within a docker container(s), it goes without saying that you first need to check your network configuration. The simplest configuration (but not necessarily the safest) is to have the JupyterHub and Jupyter Notebook containers running on the same host.
TODO: troubleshooting deployment
###JupyterHub troubleshooting when running Hub on host and and Notebook servers on remote host(s)
TODO: troubleshooting deployment
###JupyterHub troubleshooting when running Hub in docker container and and Notebook servers on same host
TODO: troubleshooting deployment
###JupyterHub troubleshooting when running Hub in docker container and and Notebook servers on remote host(s)
TODO: troubleshooting deployment with containers