Once Jupyter notebooks were shared, it became obvious that the multiuser problem had to be solved. A new version of the Jupyter software was developed, called JupyterHub. JupyterHub was specifically designed to handle multiple users, giving each user their own set of variables to work with. Actually, the system will give each user a whole new instance of the Jupyter software to each user-a brute force approach, but it works.
When JupyterHub starts up, it initiates a hub or controlling agent. The hub will start an instance of a listener or proxy for Jupyter requests. When the proxy gets requests for Jupyter it turns them over to the hub. If the hub decides that this is a new user, it will generate a new instance of the Jupyter server and attach all further interactions between that user and Jupyter to their own version of the server.
JupyterHub requires Python 3.3 or newer, and we will use the pip3 Python tool to install JupyterHub. You can check the version of Python you are running by just entering Python on a command line; the prologue will echo out the current version:
Python Python 3.6.0a4 (v3.6.0a4:017cf260936b, Aug 15 2016, 13:38:16) [GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin Type "help", "copyright", "credits" or "license" for more information.
If you need to upgrade to a new version, consult the directions on https://www.python.org/ as the directions are operating system and Python version-specific.
JupyterHub is installed much like other software, using the following commands:
npm install -g configurable-http-proxy pip3 install jupyterhub
First, we install the proxy. The -g on the proxy install makes that software available to all users:
npm install -g configurable-http-proxy /usr/local/bin/configurable-http-proxy -> /usr/local/lib/node_modules/configurable-http-proxy/bin/configurable-http-proxy /usr/local/lib └─┬ [email protected] ├─┬ [email protected] │ └── [email protected] ├─┬ [email protected] │ ├── [email protected] │ └── [email protected] ├─┬ [email protected] │ ├── [email protected] │ └── [email protected] ├── [email protected] └─┬ [email protected] ├── [email protected] ├── [email protected] ├── [email protected] ├── [email protected] ├── [email protected] ├── [email protected] └── [email protected]
Then we install JupyterHub:
pip3.6 install jupyterhub Collecting jupyterhub Downloading jupyterhub-0.6.1-py3-none-any.whl (1.3MB) 100% |████████████████████████████████| 1.4MB 789kB/s Collecting requests (from jupyterhub) Downloading requests-2.11.1-py2.py3-none-any.whl (514kB) 100% |████████████████████████████████| 522kB 1.5MB/s Collecting traitlets>=4.1 (from jupyterhub) Downloading traitlets-4.2.2-py2.py3-none-any.whl (68kB) 100% |████████████████████████████████| 71kB 4.3MB/s Collecting sqlalchemy>=1.0 (from jupyterhub) Downloading SQLAlchemy-1.0.14.tar.gz (4.8MB) 100% |████████████████████████████████| 4.8MB 267kB/s Collecting jinja2 (from jupyterhub) Downloading Jinja2-2.8-py2.py3-none-any.whl (263kB) 100% |████████████████████████████████| 266kB 838kB/s ...
We can now start JupyterHub directly from the command line:
jupyterhub
This results in the following display, which will appear in the command console window:
[I 2016-08-28 14:30:57.895 JupyterHub app:643] Writing cookie_secret to /Users/dtoomey/jupyterhub_cookie_secret [W 2016-08-28 14:30:57.953 JupyterHub app:304] Generating CONFIGPROXY_AUTH_TOKEN. Restarting the Hub will require restarting the proxy. Set CONFIGPROXY_AUTH_TOKEN env or JupyterHub.proxy_auth_token config to avoid this message. [W 2016-08-28 14:30:57.962 JupyterHub app:757] No admin users, admin interface will be unavailable. [W 2016-08-28 14:30:57.962 JupyterHub app:758] Add any administrative users to `c.Authenticator.admin_users` in config. [I 2016-08-28 14:30:57.962 JupyterHub app:785] Not using whitelist. Any authenticated user will be allowed. [I 2016-08-28 14:30:57.992 JupyterHub app:1231] Hub API listening on http://127.0.0.1:8081/hub/ [E 2016-08-28 14:30:57.998 JupyterHub app:963] Refusing to run JuptyterHub without SSL. If you are terminating SSL in another layer, pass -no-ssl to tell JupyterHub to allow the proxy to listen on HTTP.
The most important feature of this is the last line of output (which is also printed on screen in red) Refusing to run JupyterHub without SSL. JupyterHub is specifically built to account for multiple users logging in and using a single notebook, so it is complaining that it expected to have SSL running (to secure user interactions).
The last half of the last line gives us a clue what to do-we need to tell JupyterHub that we are not using a certificate/SSL. We can do that with the -no-ssl argument, as follows:
Jupyterhub -no-ssl
This leads to the expected result in the console, and leaves the server still running:
[I 2016-08-28 14:43:15.423 JupyterHub app:622] Loading cookie_secret from /Users/dtoomey/jupyterhub_cookie_secret [W 2016-08-28 14:43:15.447 JupyterHub app:304] Generating CONFIGPROXY_AUTH_TOKEN. Restarting the Hub will require restarting the proxy. Set CONFIGPROXY_AUTH_TOKEN env or JupyterHub.proxy_auth_token config to avoid this message. [W 2016-08-28 14:43:15.450 JupyterHub app:757] No admin users, admin interface will be unavailable. [W 2016-08-28 14:43:15.450 JupyterHub app:758] Add any administrative users to `c.Authenticator.admin_users` in config. [I 2016-08-28 14:43:15.451 JupyterHub app:785] Not using whitelist. Any authenticated user will be allowed. [I 2016-08-28 14:43:15.462 JupyterHub app:1231] Hub API listening on http://127.0.0.1:8081/hub/ [W 2016-08-28 14:43:15.468 JupyterHub app:959] Running JupyterHub without SSL. There better be SSL termination happening somewhere else... [I 2016-08-28 14:43:15.468 JupyterHub app:968] Starting proxy @ http://*:8000/ 14:43:15.867 - info: [ConfigProxy] Proxying http://*:8000 to http://127.0.0.1:8081 14:43:15.871 - info: [ConfigProxy] Proxy API at http://127.0.0.1:8001/api/routes [I 2016-08-28 14:43:15.900 JupyterHub app:1254] JupyterHub is now running at http://127.0.0.1:8000/
If we now go to that URL (http://127.0.0.1:8000/) shown on the last line of the output, we get to a login screen for JupyterHub:
So, we have avoided requiring SSL, but we still need to configure the users for the system. Note that, not using SSL will expose aspects of the machine that you may not want.
The JupyterHub software uses a configuration file to determine how it should work. You can generate a configuration file using JupyterHub, and provide default values using the following command:
jupyterhub -generate-config Writing default config to: jupyterhub_config.py
The file will be generated in the current directory. You need to move the file to the jupyterhub directory to enact your changes. The generated configuration file has close to 500 lines available. The start of the sample file is shown here:
# Configuration file for jupyterhub.
c = get_config()
#------------------------------------------------------------------------------
# JupyterHub configuration
#------------------------------------------------------------------------------
# An Application for starting a multiuser Jupyter Notebook server.
# JupyterHub will inherit config from: Application
# Include any kwargs to pass to the database connection. See
# sqlalchemy.create_engine for details.
# c.JupyterHub.db_kwargs = {}
# The base URL of the entire application
# c.JupyterHub.base_url = '/'
...
As you can see, most of the configuration settings are prefixed with a pound sign (#) denoting that they are commented out. The setting that is mentioned is the default value that will be applied. If you needed to change one of the settings you would remove the prefix sharp symbol and change the right-hand side of the equal sign (=) to your new value. By the way, this is a good way to test out changes: make one change, save the file, try out your change, and continue with any additional changes. As you progress, if one change does not work as expected, you need only to replace the pound sign and you are back to a working position.
We will look at a few of the configuration options available. It is interesting to note that many of the settings in this file are Python settings, not particular to JupyterHub. The list of items includes the following:
|
Area |
Description |
|
JupyterHub |
Settings for JupyterHub |
|
LoggingConfigurable |
Logging information layout |
|
SingletonConfigurable |
A configurable that only allows one instance |
|
Application |
Date format and logging level |
|
Security |
SSL certificate |
|
Spawner |
How the hub starts new instances of Jupyter for new users |
|
LocalProcessSpawner |
Uses |
|
Authenticator |
The method(s) used to authenticate the user |
|
PAMAuthenticator |
Interaction with Linux to login |
|
LocalAuthenticator |
Checks for local users, and can attempt to create them if they exist |
I made no changes to the configuration file to get my installation up and running. By default, the configuration uses the PEM system, which will use the user credentials manually added into the form and operating system that you are running on to pass in credentials (as if they were logging into the machine) for validation. Note that, there are cases where an SSL error occurs in this step, which will require you to rename the ./jupyter directory.
If you are seeing the message JupyterHub single-user server requires notebook >= 4.0 in the console log when trying to login to your JupyterHub installation, you need to update the base Jupyter using the following command:
pip3 install jupyter
This will update your base jupyter to the latest version, currently 4.1.
Tip
If you do not have pip3 installed, you need to upgrade to Python 3 or newer. See the documentation at https://www.python.org/ for the steps for your system.
Now, you can start JupyterHub using the following command line:
jupyterhub -no-ssl
Alternatively, you may use a certificate from the previous chapter. Log in on the login screen using the same credentials you use to login to the machine (remember, JupyterHub is using PEM, which calls into your operating system to validate credentials). You will end up in something that looks very much like your standard Jupyter homepage:
It looks very similar, except there are now two additional buttons in the top right of the screen:
- Control Panel
- Logout
Clicking on the Logout button logs you out of JupyterHub and redirects you to the login screen.
Clicking on the Control Panel button brings you to a new screen with two options, shown here:
- Stop My Server
- My Server
Clicking on the Stop My Server button stops your Jupyter installation and brings you to a page with one button: My Server (as shown after this section). You might also have noticed the changes that have occurred in the console log of your command line:
[I 2016-08-28 20:22:16.578 JupyterHub log:100] 200 GET /hub/api/authorizations/cookie/jupyter-hub-token-dtoomey/[secret] ([email protected]) 13.31ms [I 2016-08-28 20:23:01.181 JupyterHub orm:178] Removing user dtoomey from proxy [I 2016-08-28 20:23:01.186 dtoomey notebookapp:1083] Shutting down kernels [I 2016-08-28 20:23:01.417 JupyterHub base:367] User dtoomey server took 0.236 seconds to stop [I 2016-08-28 20:23:01.422 JupyterHub log:100] 204 DELETE /hub/api/users/dtoomey/server ([email protected]) 243.06ms
Clicking on the My Server button brings you back to the Jupyter home page. If you had hit the Stop My Server button earlier, then the underlying Jupyter software would be restarted, as you may notice in the console output (which I have shown here):
I 2016-08-28 20:26:16.356 JupyterHub base:306] User dtoomey server took 1.007 seconds to start [I 2016-08-28 20:26:16.356 JupyterHub orm:159] Adding user dtoomey to proxy /user/dtoomey => http://127.0.0.1:50972 [I 2016-08-28 20:26:16.372 dtoomey log:47] 302 GET /user/dtoomey (127.0.0.1) 0.73ms [I 2016-08-28 20:26:16.376 JupyterHub log:100] 302 GET /hub/user/dtoomey ([email protected]) 1019.24ms [I 2016-08-28 20:26:16.413 JupyterHub log:100] 200 GET /hub/api/authorizations/cookie/jupyter-hub-token-dtoomey/[secret] ([email protected]) 10.75ms
So, in summary, with JupyterHub we have an installation of Jupyter that will maintain a separate instance of the Jupyter software for each user, thereby avoiding any collision due to variable values. The software knows whether to instantiate a new instance of Jupyter since the user logs in to the application and the system maintains a user list.