jupyterhub / jupyterhub-deploy-teaching

Reference deployment of JupyterHub and nbgrader on a single server

Technical Overview | Installation | Configuration | Docker | Contributing | License | Help and Resources

---

JupyterHub

With JupyterHub you can create a multi-user Hub that spawns, manages, and proxies multiple instances of the single-user Jupyter notebook server.

Project Jupyter created JupyterHub to support many users. The Hub can offer notebook servers to a class of students, a corporate data science workgroup, a scientific research project, or a high-performance computing group.

Technical overview

Three main actors make up JupyterHub:

• multi-user Hub (tornado process)
• configurable http proxy (node-http-proxy)
• multiple single-user Jupyter notebook servers (Python/Jupyter/tornado)

Basic principles for operation are:

• Hub launches a proxy.
• The Proxy forwards all requests to Hub by default.
• Hub handles login and spawns single-user servers on demand.
• Hub configures proxy to forward URL prefixes to the single-user notebook servers.

JupyterHub also provides a REST API for administration of the Hub and its users.

Installation

Check prerequisites

• A Linux/Unix based system

• Python 3.8 or greater

• nodejs/npm

  • If you are using conda, the nodejs and npm dependencies will be installed for you by conda.

  • If you are using pip, install a recent version (at least 12.0) of nodejs/npm.

• If using the default PAM Authenticator, a pluggable authentication module (PAM).

• TLS certificate and key for HTTPS communication

• Domain name

Install packages

Using conda

To install JupyterHub along with its dependencies including nodejs/npm:

conda install -c conda-forge jupyterhub

If you plan to run notebook servers locally, install JupyterLab or Jupyter notebook:

conda install jupyterlab
conda install notebook

Using pip

JupyterHub can be installed with pip, and the proxy with npm:

npm install -g configurable-http-proxy
python3 -m pip install jupyterhub

If you plan to run notebook servers locally, you will need to install JupyterLab or Jupyter notebook:

python3 -m pip install --upgrade jupyterlab
python3 -m pip install --upgrade notebook

Run the Hub server

To start the Hub server, run the command:

jupyterhub

Visit http://localhost:8000 in your browser, and sign in with your system username and password.

Note: To allow multiple users to sign in to the server, you will need to run the jupyterhub command as a privileged user, such as root. The wiki describes how to run the server as a less privileged user, which requires more configuration of the system.

Configuration

The Getting Started section of the documentation explains the common steps in setting up JupyterHub.

The JupyterHub tutorial provides an in-depth video and sample configurations of JupyterHub.

Create a configuration file

To generate a default config file with settings and descriptions:

jupyterhub --generate-config

Start the Hub

To start the Hub on a specific url and port 10.0.1.2:443 with https:

jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert

Authenticators

Authenticator	Description
PAMAuthenticator	Default, built-in authenticator
OAuthenticator	OAuth + JupyterHub Authenticator = OAuthenticator
ldapauthenticator	Simple LDAP Authenticator Plugin for JupyterHub
kerberosauthenticator	Kerberos Authenticator Plugin for JupyterHub

Spawners

Spawner	Description
LocalProcessSpawner	Default, built-in spawner starts single-user servers as local processes
dockerspawner	Spawn single-user servers in Docker containers
kubespawner	Kubernetes spawner for JupyterHub
sudospawner	Spawn single-user servers without being root
systemdspawner	Spawn single-user notebook servers using systemd
batchspawner	Designed for clusters using batch scheduling software
yarnspawner	Spawn single-user notebook servers distributed on a Hadoop cluster
wrapspawner	WrapSpawner and ProfilesSpawner enabling runtime configuration of spawners

Docker

A starter docker image for JupyterHub gives a baseline deployment of JupyterHub using Docker.

Important: This quay.io/jupyterhub/jupyterhub image contains only the Hub itself, with no configuration. In general, one needs to make a derivative image, with at least a jupyterhub_config.py setting up an Authenticator and/or a Spawner. To run the single-user servers, which may be on the same system as the Hub or not, Jupyter Notebook version 4 or greater must be installed.

The JupyterHub docker image can be started with the following command:

docker run -p 8000:8000 -d --name jupyterhub quay.io/jupyterhub/jupyterhub jupyterhub

This command will create a container named jupyterhub that you can stop and resume with docker stop/start.

The Hub service will be listening on all interfaces at port 8000, which makes this a good choice for testing JupyterHub on your desktop or laptop.

If you want to run docker on a computer that has a public IP then you should (as in MUST) secure it with ssl by adding ssl options to your docker configuration or by using an ssl enabled proxy.

Mounting volumes will allow you to store data outside the docker image (host system) so it will be persistent, even when you start a new image.

The command docker exec -it jupyterhub bash will spawn a root shell in your docker container. You can use the root shell to create system users in the container. These accounts will be used for authentication in JupyterHub's default configuration.

Contributing

If you would like to contribute to the project, please read our contributor documentation and the CONTRIBUTING.md. The CONTRIBUTING.md file explains how to set up a development installation, how to run the test suite, and how to contribute to documentation.

For a high-level view of the vision and next directions of the project, see the JupyterHub community roadmap.

A note about platform support

JupyterHub is supported on Linux/Unix based systems.

JupyterHub officially does not support Windows. You may be able to use JupyterHub on Windows if you use a Spawner and Authenticator that work on Windows, but the JupyterHub defaults will not. Bugs reported on Windows will not be accepted, and the test suite will not run on Windows. Small patches that fix minor Windows compatibility issues (such as basic installation) may be accepted, however. For Windows-based systems, we would recommend running JupyterHub in a docker container or Linux VM.

Additional Reference: Tornado's documentation on Windows platform support

License

We use a shared copyright model that enables all contributors to maintain the copyright on their contributions.

All code is licensed under the terms of the revised BSD license.

Help and resources

We encourage you to ask questions and share ideas on the Jupyter community forum. You can also talk with us on our JupyterHub Gitter channel.

• Reporting Issues
• JupyterHub tutorial
• Documentation for JupyterHub
• Documentation for JupyterHub's REST API
• Documentation for Project Jupyter
• Project Jupyter website
• Project Jupyter community

JupyterHub follows the Jupyter Community Guides.

---

Technical Overview | Installation | Configuration | Docker | Contributing | License | Help and Resources

jupyterhub-deploy-teaching's Issues

failed to install jupyterlab/hub-extension

TASK [python : install jupyterlab extensions] ************************************************************************************************
failed: [teaching.nextnet.top] (item=@jupyterlab/hub-extension) => {"changed": true, "cmd": ["jupyter", "labextension", "install", "@jupyterlab/hub-extension"], "delta": "0:00:04.666373", "end": "2018-08-11 11:27:56.508112", "item": "@jupyterlab/hub-extension", "msg": "non-zero return code", "rc": 1, "start": "2018-08-11 11:27:51.841739", "stderr": "> npm pack @jupyterlab/hub-extension
Traceback (most recent call last):
  File \"/opt/conda/bin/jupyter-labextension\", line 6, in <module>
    sys.exit(jupyterlab.labextensions.main())
  File \"/opt/conda/lib/python3.6/site-packages/jupyter_core/application.py\", line 266, in launch_instance
    return super(JupyterApp, cls).launch_instance(argv=argv, **kwargs)
  File \"/opt/conda/lib/python3.6/site-packages/traitlets/config/application.py\", line 658, in launch_instance
    app.start()
  File \"/opt/conda/lib/python3.6/site-packages/jupyterlab/labextensions.py\", line 168, in start
    super(LabExtensionApp, self).start()
  File \"/opt/conda/lib/python3.6/site-packages/jupyter_core/application.py\", line 255, in start
    self.subapp.start()
  File \"/opt/conda/lib/python3.6/site-packages/jupyterlab/labextensions.py\", line 58, in start
    for arg in self.extra_args]
  File \"/opt/conda/lib/python3.6/site-packages/jupyterlab/labextensions.py\", line 58, in <listcomp>
    for arg in self.extra_args]
  File \"/opt/conda/lib/python3.6/site-packages/jupyterlab/commands.py\", line 125, in install_extension
    return IOLoop.instance().run_sync(func)
  File \"/opt/conda/lib/python3.6/site-packages/tornado/ioloop.py\", line 576, in run_sync
    return future_cell[0].result()
  File \"/opt/conda/lib/python3.6/site-packages/tornado/gen.py\", line 1147, in run
    yielded = self.gen.send(value)
  File \"/opt/conda/lib/python3.6/site-packages/jupyterlab/commands.py\", line 187, in install_extension_async
    raise ValueError(msg)
ValueError: 
\"@jupyterlab/[email protected]\" is not compatible with the current JupyterLab
Conflicting Dependencies:
JupyterLab              Extension            Package
>=0.11.1-0 <0.12.0-0    >=0.17.0-0 <0.18.0-0 @jupyterlab/application
>=0.11.1-0 <0.12.0-0    >=0.17.0-0 <0.18.0-0 @jupyterlab/apputils
>=0.11.1-0 <0.12.0-0    >=2.0.0-0 <3.0.0-0   @jupyterlab/coreutils", "stderr_lines": ["> npm pack @jupyterlab/hub-extension", "Traceback (most recent call last):", "  File \"/opt/conda/bin/jupyter-labextension\", line 6, in <module>", "    sys.exit(jupyterlab.labextensions.main())", "  File \"/opt/conda/lib/python3.6/site-packages/jupyter_core/application.py\", line 266, in launch_instance", "    return super(JupyterApp, cls).launch_instance(argv=argv, **kwargs)", "  File \"/opt/conda/lib/python3.6/site-packages/traitlets/config/application.py\", line 658, in launch_instance", "    app.start()", "  File \"/opt/conda/lib/python3.6/site-packages/jupyterlab/labextensions.py\", line 168, in start", "    super(LabExtensionApp, self).start()", "  File \"/opt/conda/lib/python3.6/site-packages/jupyter_core/application.py\", line 255, in start", "    self.subapp.start()", "  File \"/opt/conda/lib/python3.6/site-packages/jupyterlab/labextensions.py\", line 58, in start", "    for arg in self.extra_args]", "  File \"/opt/conda/lib/python3.6/site-packages/jupyterlab/labextensions.py\", line 58, in <listcomp>", "    for arg in self.extra_args]", "  File \"/opt/conda/lib/python3.6/site-packages/jupyterlab/commands.py\", line 125, in install_extension", "    return IOLoop.instance().run_sync(func)", "  File \"/opt/conda/lib/python3.6/site-packages/tornado/ioloop.py\", line 576, in run_sync", "    return future_cell[0].result()", "  File \"/opt/conda/lib/python3.6/site-packages/tornado/gen.py\", line 1147, in run", "    yielded = self.gen.send(value)", "  File \"/opt/conda/lib/python3.6/site-packages/jupyterlab/commands.py\", line 187, in install_extension_async", "    raise ValueError(msg)", "ValueError: ", "\"@jupyterlab/[email protected]\" is not compatible with the current JupyterLab", "Conflicting Dependencies:", "JupyterLab              Extension            Package", ">=0.11.1-0 <0.12.0-0    >=0.17.0-0 <0.18.0-0 @jupyterlab/application", ">=0.11.1-0 <0.12.0-0    >=0.17.0-0 <0.18.0-0 @jupyterlab/apputils", ">=0.11.1-0 <0.12.0-0    >=2.0.0-0 <3.0.0-0   @jupyterlab/coreutils"], "stdout": "npm notice 
npm notice package: @jupyterlab/[email protected]
npm notice === Tarball Contents === 
npm notice 908B  package.json  
npm notice 1.5kB LICENSE       
npm notice 2.0kB README.md     
npm notice 351B  lib/index.d.ts
npm notice 2.6kB lib/index.js  
npm notice === Tarball Details === 
npm notice name:          @jupyterlab/hub-extension               
npm notice version:       0.10.0                                  
npm notice filename:      jupyterlab-hub-extension-0.10.0.tgz     
npm notice package size:  3.3 kB                                  
npm notice unpacked size: 7.3 kB                                  
npm notice shasum:        9c8bdb4087c79ab80729e88eb9789dad5c448bfd
npm notice integrity:     sha512-G+vO7gXDHFwms[...]x6t/et/MfFdQA==
npm notice total files:   5                                       
npm notice 
jupyterlab-hub-extension-0.10.0.tgz", "stdout_lines": ["npm notice ", "npm notice package: @jupyterlab/[email protected]", "npm notice === Tarball Contents === ", "npm notice 908B  package.json  ", "npm notice 1.5kB LICENSE       ", "npm notice 2.0kB README.md     ", "npm notice 351B  lib/index.d.ts", "npm notice 2.6kB lib/index.js  ", "npm notice === Tarball Details === ", "npm notice name:          @jupyterlab/hub-extension               ", "npm notice version:       0.10.0                                  ", "npm notice filename:      jupyterlab-hub-extension-0.10.0.tgz     ", "npm notice package size:  3.3 kB                                  ", "npm notice unpacked size: 7.3 kB                                  ", "npm notice shasum:        9c8bdb4087c79ab80729e88eb9789dad5c448bfd", "npm notice integrity:     sha512-G+vO7gXDHFwms[...]x6t/et/MfFdQA==", "npm notice total files:   5                                       ", "npm notice ", "jupyterlab-hub-extension-0.10.0.tgz"]}

Consider using systemdspawner for doing resource limits

Filing this per @minrk's suggestion!

With https://github.com/jupyterhub/systemdspawner you can now have per-user limits for RAM / CPU quite easily, and the semantics of the spawner are very similar to the default spawner. Consider using it for this deployment.

Allow jupyterhub to be restarted w/o stopping single user servers

We are currently managing the jupyterhub process through supervisord. When jupyterhub is reconfigured and restarted through supervisord, the single user servers are killed. It would be very helpful to be able to reconfigure+restart the hub while leaving the single user servers alive. What would be needed to accomplish this?

@minrk @willingc

cull idle servers not working

I have configured the cull idle servers and it doesn't seem to be working. Here is my config:

# Optionally cull idle single user servers
use_cull_idle_servers: true
# The username and API token for culling idle servers
# Create using something like `openssl rand -hex 32`
cull_idle_servers_owner: root
cull_idle_servers_hubapi_token: '8ddef1a469ffbe3a86deb60d664ca53bc2bbadcca1145889014ef214a9e9c6fb'
# The interval (in seconds) for checking for idle servers to cull
cull_every: 600
# The idle timeout (in seconds)
cull_timeout: 259200

Which leads to the following supervisord config:

environment=JPY_API_TOKEN='8ddef1a469ffbe3a86deb60d664ca53bc2bbadcca1145889014ef214a9e9c6fb'
command=/opt/conda/bin/python3 /srv/jupyterhub/cull_idle_servers.py --cull-every=600 --timeout=259200
redirect_stderr=true
stdout_logfile=/var/log/jupyterhub/cull_idle_servers.log
autostart=true
autorestart=false
stopasgroup=true
user=root
directory=/srv/jupyterhub

I have confirmed that the .py script is installed in /srv/jupyterhub. When starting cull idle servers I see the following in the log:

Traceback (most recent call last):
  File "/srv/jupyterhub/cull_idle_servers.py", line 76, in <module>
    loop.run_sync(cull)
  File "/opt/conda/lib/python3.5/site-packages/tornado/ioloop.py", line 457, in run_sync
    return future_cell[0].result()
  File "/opt/conda/lib/python3.5/site-packages/tornado/concurrent.py", line 237, in result
    raise_exc_info(self._exc_info)
  File "<string>", line 3, in raise_exc_info
  File "/opt/conda/lib/python3.5/site-packages/tornado/gen.py", line 1021, in run
    yielded = self.gen.throw(*exc_info)
  File "/srv/jupyterhub/cull_idle_servers.py", line 43, in cull_idle
    resp = yield client.fetch(req)
  File "/opt/conda/lib/python3.5/site-packages/tornado/gen.py", line 1015, in run
    value = future.result()
  File "/opt/conda/lib/python3.5/site-packages/tornado/concurrent.py", line 237, in result
    raise_exc_info(self._exc_info)
  File "<string>", line 3, in raise_exc_info
tornado.httpclient.HTTPError: HTTP 403: Forbidden

And the following lines in my jupyterhub config file:

c.JupyterHub.api_tokens.update({
    '8ddef1a469ffbe3a86deb60d664ca53bc2bbadcca1145889014ef214a9e9c6fb': 'root'
})

As far as I can tell, all of the things are in the right place, but it doesn't look like the API token is being accepted by the hub. Other odd bits:

• While the host_vars files takes a cull_idle_servers_owner (I am using root) that isn't used anywhere other than the jupyterhub config file. The user owning the cull idle server process is hardcoded to root in the supervisor config file.

JupyterHub itself is working fine on this system.

Archiving this repository in favour of TLJH

Should we archive this repository and point people at https://github.com/jupyterhub/the-littlest-jupyterhub?

Sometimes people use the instructions from this repository and run into problems (it is unknown how many use it and are happy!). For those with problems my impression is that the best piece of advice is "don't use this, use TLJH instead your problems are probably going to go away by switching")

There has been no activity in this repository for a long time which often means there is no one maintaining it any more. From a quick read of the goals/use cases it seems like TLJH covers those well.

update documentation on formgrader configuration

http://jupyterhub-deploy-teaching.readthedocs.io/en/latest/configure-nbgrader.html needs to be updated, since there is no deploy_formgrade.yml anymore and everything is configured through host_vars/<fqdn> file

PS I also think deploy_formgrade.yml was not completely useless, since configuration is essentially trial-and-error, and running it through deploy.yml would incur too much waiting.

spawner error "AttributeError: No such service field: token" jupyterhub

It seems that 'token': '{{cull_idle_servers_hubapi_token}}',

in jupyterhub_config.py.j2

should be
'api_token': '{{cull_idle_servers_hubapi_token}}',

Test Ansible 2.2+ with Python 3 support

Testing instructions are found here:
http://docs.ansible.com/ansible/python_3_support.html

jupyterlab_default: false has no effect

I installed the repo on a server, and logged in with a user. I was expecting to see a regular Jupyter notebook interface; however, I was greeted by JupyterLab instead. I tried removing the /lab part from the URL, but I get redirected to there nevertheless.

The variable jupyterlab_default had been set to false in the host_vars file. I followed the installation instructions here.

Jupyterhub won't start after deployment

I try to deploy the jupyterhub-deploy-teaching master version. Every step of deploy.yml executes without error except for start_jupyterhub.

At first it threw the following error:

TASK [start_jupyterhub : restart jupyterhub with supervisor] *********************************************************************************************************************************************************************************
fatal: [www.datascienceauditor.nl]: FAILED! => {"changed": false, "failed": true, "msg": "jupyterhub: ERROR (not running)\njupyterhub: ERROR (spawn error)\n"}

The error logs in /var/log/jupyterhub/jupyterhub.log mention that jupyterhub has trouble adding users that already exist:

[E 2017-09-13 10:51:20.557 JupyterHub app:1527]
    Traceback (most recent call last):
      File "/opt/conda/lib/python3.5/site-packages/jupyterhub/app.py", line 1524, in launch_instance_async
        yield self.initialize(argv)
      File "/opt/conda/lib/python3.5/types.py", line 179, in throw
        return self.__wrapped.throw(tp, *rest)
      File "/opt/conda/lib/python3.5/site-packages/jupyterhub/app.py", line 1311, in initialize
        yield self.init_groups()
      File "/opt/conda/lib/python3.5/site-packages/jupyterhub/app.py", line 935, in init_groups
        raise ValueError("Username %r is not in whitelist" % username)
    ValueError: Username 'instructor2' is not in whitelist

I removed the sqlite database from /srv/jupyterhub/jupyterhub.sqlite which resolves the problem of the ansible-playbook execution. Now everything executes fine without any errors. Nevertheless, when visiting my domain I get the nginx 502 Bad Gateway message so it seems that jupyterhub is not running.

If I ssh into the host machine and run jupyterhub it fires up jupyterhub and when I visit the domain I can see the login screen. But firing up jupyterhub this way uses some default configuration and not the one deployed by the ansible-playbook. Running jupyterhub with the path to the config file gives

sudo /opt/conda/bin/jupyterhub --config =/etc/jupyterhub/jupyterhub_config.py
[I 2017-09-13 11:03:14.112 JupyterHub app:745] Writing cookie_secret to /etc/jupyterhub/jupyterhub_cookie_secret
[W 2017-09-13 11:03:14.463 JupyterHub app:365]
    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 2017-09-13 11:03:14.495 JupyterHub app:864] No admin users, admin interface will be unavailable.
[W 2017-09-13 11:03:14.495 JupyterHub app:865] Add any administrative users to `c.Authenticator.admin_users` in config.
[I 2017-09-13 11:03:14.496 JupyterHub app:892] Not using whitelist. Any authenticated user will be allowed.
[I 2017-09-13 11:03:14.511 JupyterHub app:1453] Hub API listening on http://127.0.0.1:8081/hub/
[W 2017-09-13 11:03:14.515 JupyterHub app:1174] Running JupyterHub without SSL.  I hope there is SSL termination happening somewhere else...
[I 2017-09-13 11:03:14.515 JupyterHub app:1176] Starting proxy @ http://*:8000/
[E 2017-09-13 11:03:14.517 JupyterHub app:1184] Failed to find proxy ['configurable-http-proxy']
    The proxy can be installed with `npm install -g configurable-http-proxy`

So I'm a bit lost right now, is there anyway to resolve this problem?

Issue with Github Authentication

I've been able to get Jupyterhub/Nbgrader working with this configuration. Thanks for all the work putting it together!

However, when using Github Authentication I get a 403 Error. I've tried it on two different installs.

I have (1) Verified that the callback url is correct. (2) verified that the client url and the client secret are correct. (3) Examined the /var/log/jupyterhub log and the nginx logs but there doesn't seem to be an error list. (4) I've verified that my github username also has an linux username. (5) Verified that all settings in /etc/jupyterhub/jupyterhub_config.py are consistent with documentation.

Anywhere else I should look?

failed to install Minimal C Kernel

I tried to install Minimal C Kernel described in this link https://github.com/brendan-rius/jupyter-c-kernel
but after following the steps in the link. It does not add C kernel in the distribution.
Can anyone elaborate on the steps as to how to add this C kernel in the deployment using ansible.

Problem upgrading to Jupyterlab 1.0.2

Hello,

I'm trying to upgrade the jupyterlab version to the new stable version 1.0.2. To do this, I execute the command

conda install -c conda-forge jupyterlab

in the base conda environment that is installed by default via the ansible script.

In this process, python gets upgraded to version 3.7. However, after everything is finished the jupyterhub gives me a 502 Bad Gateway and I haven't been able to fix it.

What is the correct way to upgrade the hub to python 3.7 and be able to use the latest version of jupyterlab?

thanks in advance for any help.

ubuntu 16.04

Does it work in ubuntu 16.04?
Which versions of ubuntu and ansible this script was tested against?
I encountered some problems - some packages are not installed.

nginx not restarting/loading new config

A fresh deployment on ubuntu 14 LTS needed an extra service nginx restart before it would run.

@minrk @willingc

Update docs build to use conda for RTD

Edit readthedocs.yml to use conda. Correct build failure on RTD due to RTD trying to read the ansible submodule.

nbgrader too welded to configuration

Some original use cases for this deployment seem to be broken right now:

• Deploy with no nbgrader config at all: I know the current name of this deployment is jupyterhub-deploy-teaching but that is a bit of a misnomer. In reality, this deployment is also very well matched to small teams of data scientists working on a single shared system. Originally, the nbgrader config could be left as is and everything would work fine. That is not the case today as the default config will cause the user instructor to be used. We should add a use_nbgrader flag to completely disable it.
• Multiple nbgrader configs, setup after initial deployment: We often run a single server for a long period of time with this deployment and over time add more nbgrader/formgrade configurations. Previously, I could edit the nbgrader vars in the host_vars file and rerun the deploy-formgrade.yml playbook to add a new nbgrader setup. That no longer works as the formgrade user and the formgrade API token is injected into the jupyterhub config file. It is important to support adding new nbgrader courses, without restarting or reconfiguring the hub. To support this usage case, we may want to move the vars related to a particular nbgrader course to the deploy-formgrade.yml playbook to make that relationship more clear.

cull-idle as a Hub service doesn't work

Bug description

I have followed exactly the steps here .

Expected behaviour

When the relevant seconds pass as defined in the jupyterhub_config.py , the cull-idle service should stop the idle server of each user. So that when going to navigate the page, no terminals should be able to be started, no notebooks etc, unless the user explicitly presses Start server . (am I wrong?)

Actual behaviour

When the relevant seconds pass, all that happens is this output in the log:
200 GET /hub/api/users ([email protected]) 10.47ms
And with this the server continues running normally, meaning I can start a terminal, make files etc.

Your personal set up

• Version:

JupyterHub version 1.1.0
oauthenticator.generic.GenericOAuthenticator-0.11.0
Using Spawner: jupyterhub.spawner.LocalProcessSpawner-1.1.0
Using Proxy: jupyterhub.proxy.ConfigurableHTTPProxy-1.1.0

• Configuration:

import sys
c.JupyterHub.last_activity_interval = 300
c.GenericOAuthenticator.auth_refresh_age = 800
c.JupyterHub.shutdown_on_logout = True
from oauthenticator.generic import GenericOAuthenticator
c.JupyterHub.authenticator_class = GenericOAuthenticator
c.Authenticator.enable_auth_state = True
c.LocalGenericOAuthenticator.refresh_pre_spawn = True
c.LocalGenericOAuthenticator.pre_spawn_start

c.JupyterHub.services = [{
    'name': 'cull-idle',
    'admin': True,
    'command': [sys.executable, '/home/elena/cull_idle_servers.py', '--timeout=600'],
    }
]

Running as root .

No module named 'distutils.spawn'

Bug description

Running Playbook results in error => No module named 'distutils.spawn'

Can be resolved with

sudo apt install python3-distutils -y

• OS: Ubuntu 18.04 LTS

Formgrader 404 (only for "owner")

Hi! First of all, thank you for developing nbgrader (@jhamrick) and this particular jupyterhub deployment! I installed and configured out server to run this deployment a while ago, and everything worked smoothly (including the formgrader). However, after rebooting the server, suddenty I'm unable to access the formgrader (404 error). Interestingly, as the "owner" (as specified in the host_vars file) I'm the only one who cannot access the formgrader; other graders (and even students) can access it.

My set-up is largely the default setup as specified in the master branch of jupyterhub-deploy-teaching, apart from a couple of things.

• I have used the changes suggested in #83 to make nbgrader==0.5.3 work
• I upgraded jupyterhub to version 0.7.2. as suggested in #88 to check whether this resolves the 404 error (it doesn't)

My nbgrader_config.py file (located in ~/.jupyter) looks like the following:

# Ansible managed
# Configuration file for nbgrader.
c = get_config()

c.CourseDirectory.root = '/home/lsnoek1/nbgrader/neuroimaging_bold'
c.Exchange.course_id = 'neuroimaging_bold'

My nbextensions are set as follows (output from the command jupyter nbextension list):

Known nbextensions:
  config dir: /opt/conda/etc/jupyter/nbconfig
    notebook section
      validate_assignment/main  enabled
      - Validating: OK
      create_assignment/main  enabled
      - Validating: OK
    tree section
      assignment_list/main  enabled
      - Validating: OK
      formgrader/main  enabled
      - Validating: OK

And my /etc/jupyterhub/jupyterhub_config.py looks like this:

# Ansible managed
# Configuration file for jupyterhub.

c = get_config()
c.JupyterHub.ip = u'<our server address>'
c.JupyterHub.port = 8000
c.JupyterHub.cookie_secret_file = u'/srv/jupyterhub/cookie_secret'
c.JupyterHub.db_url = u'/srv/jupyterhub/jupyterhub.sqlite'
c.JupyterHub.proxy_auth_token = u''
c.JupyterHub.confirm_no_ssl = True

c.JupyterHub.load_groups = {
'formgrade-neuroimaging_bold': ['lsnoek1','grader2','grader3',],
}

c.Authenticator.admin_users = {'lsnoek1','grader1','grader2'}

c.Authenticator.whitelist = {'lsnoek1','grader1','grader2','student1', 'student2', <etc>}

c.JupyterHub.services = [
]   # the content of this field was removed as indicated in PR #88

I hope someone can help me because the course is starting soon, and I would love to use the formgrader for manual grading/giving feedback :)

Again, thanks a lot for developing this great tool/deployment scheme, and I'm looking forward to any tips that might help me solve this issue!

-Lukas

Error with conda.py

Hi! First of all, thanks for this great job.

I'm getting a lot of errors of this kind

failed: [sapho - longwing](item = ipywidgets) => {
    "failed": true,
    "item": "ipywidgets",
    "module_stderr": "\
        OpenSSH_7.2p2 Ubuntu-4ubuntu2.2, OpenSSL 1.0.2g  1 Mar 2016    \
        debug1: Reading configuration data /etc/ssh/ssh_config    \
        debug1: /etc/ssh/ssh_config line 19: Applying options for *    \
        debug1: auto-mux: Trying existing master    \
        debug2: fd 3 setting O_NONBLOCK    \
        debug2: mux_client_hello_exchange: master version 4    \
        debug3: mux_client_forwards: request forwardings: 0 local, 0 remote    \
        debug3: mux_client_request_session: entering    \
        debug3: mux_client_request_alive: entering    \
        debug3: mux_client_request_alive: done pid = 897    \
        debug3: mux_client_request_session: session request sent    \
        debug1: mux_client_request_session: master session id: 2    \
        debug3: mux_client_read_packet: read header failed: Broken pipe    \
        debug2: Received exit status from master 0    \
        Shared connection to sapho-longwing closed.    \
    ",
    "module_stdout": "\
        Traceback (most recent call last):    \
          File \"/tmp/ansible_dRn5ki/ansible_module_conda.py\", line 296, in <module>    \
            main()    \
          File \"/tmp/ansible_dRn5ki/ansible_module_conda.py\", line 281, in main    \
            installed, installed_version = _check_installed(module, conda, name)    \
          File \"/tmp/ansible_dRn5ki/ansible_module_conda.py\", line 141, in _check_installed    \
            pname, pversion, pdist = other.rsplit('-', 2)    \
        AttributeError: 'dict' object has no attribute 'rsplit'    \
    ",
    "msg": "MODULE FAILURE",
    "rc": 0
}

With many packages. The problem is that sometimes object becomes a dict object. In thos case I solved the problem with this

if isinstance(other, dict):
    pname = other.get('name', '') 
    pversion = other.get('version', '') 
else:
    pname, pversion, pdist = other.rsplit('-', 2)

conda failures on 64 bit linux

Trying a deployment on master today found this:

TASK [python : conda install ipython and jupyter deps] *************************
failed: [test.calpolydatascience.org] (item=notebook=4.3) => {"changed": true, "cmd": ["conda", "install", "name=notebook=4.3", "state=present"], "delta": "0:00:05.928944", "end": "2017-01-03 23:46:52.658099", "failed": true, "item": "notebook=4.3", "rc": 1, "start": "2017-01-03 23:46:46.729155", "stderr": "Error: Packages missing in current linux-64 channels: \n  - name notebook 4.3\n  - state present*\n\nClose matches found; did you mean one of these?\n\n    state: statsd, static\n\nYou can search for packages on anaconda.org with\n\n    anaconda search -t conda state\n\n(and similarly for the other packages)\n\nYou may need to install the anaconda-client command line client with\n\n    conda install anaconda-client", "stdout": "Fetching package metadata .........\nSolving package specifications: .", "stdout_lines": ["Fetching package metadata .........", "Solving package specifications: ."], "warnings": []}
failed: [test.calpolydatascience.org] (item=ipyparallel) => {"changed": true, "cmd": ["conda", "install", "name=ipyparallel", "state=present"], "delta": "0:00:04.542296", "end": "2017-01-03 23:46:58.200532", "failed": true, "item": "ipyparallel", "rc": 1, "start": "2017-01-03 23:46:53.658236", "stderr": "Error: Packages missing in current linux-64 channels: \n  - name ipyparallel*\n  - state present*\n\nClose matches found; did you mean one of these?\n\n    state: statsd, static\n\nYou can search for packages on anaconda.org with\n\n    anaconda search -t conda state\n\n(and similarly for the other packages)\n\nYou may need to install the anaconda-client command line client with\n\n    conda install anaconda-client", "stdout": "Fetching package metadata .........\nSolving package specifications: .", "stdout_lines": ["Fetching package metadata .........", "Solving package specifications: ."], "warnings": []}
failed: [test.calpolydatascience.org] (item=ipykernel) => {"changed": true, "cmd": ["conda", "install", "name=ipykernel", "state=present"], "delta": "0:00:04.572776", "end": "2017-01-03 23:47:03.764801", "failed": true, "item": "ipykernel", "rc": 1, "start": "2017-01-03 23:46:59.192025", "stderr": "Error: Packages missing in current linux-64 channels: \n  - name ipykernel*\n  - state present*\n\nClose matches found; did you mean one of these?\n\n    state: statsd, static\n\nYou can search for packages on anaconda.org with\n\n    anaconda search -t conda state\n\n(and similarly for the other packages)\n\nYou may need to install the anaconda-client command line client with\n\n    conda install anaconda-client", "stdout": "Fetching package metadata .........\nSolving package specifications: .", "stdout_lines": ["Fetching package metadata .........", "Solving package specifications: ."], "warnings": []}
failed: [test.calpolydatascience.org] (item=nbconvert) => {"changed": true, "cmd": ["conda", "install", "name=nbconvert", "state=present"], "delta": "0:00:04.491097", "end": "2017-01-03 23:47:09.371406", "failed": true, "item": "nbconvert", "rc": 1, "start": "2017-01-03 23:47:04.880309", "stderr": "Error: Packages missing in current linux-64 channels: \n  - name nbconvert*\n  - state present*\n\nClose matches found; did you mean one of these?\n\n    state: statsd, static\n\nYou can search for packages on anaconda.org with\n\n    anaconda search -t conda state\n\n(and similarly for the other packages)\n\nYou may need to install the anaconda-client command line client with\n\n    conda install anaconda-client", "stdout": "Fetching package metadata .........\nSolving package specifications: .", "stdout_lines": ["Fetching package metadata .........", "Solving package specifications: ."], "warnings": []}
failed: [test.calpolydatascience.org] (item=pandoc) => {"changed": true, "cmd": ["conda", "install", "name=pandoc", "state=present"], "delta": "0:00:04.543237", "end": "2017-01-03 23:47:15.415850", "failed": true, "item": "pandoc", "rc": 1, "start": "2017-01-03 23:47:10.872613", "stderr": "Error: Packages missing in current linux-64 channels: \n  - name pandoc*\n  - state present*\n\nClose matches found; did you mean one of these?\n\n    state: statsd, static\n\nYou can search for packages on anaconda.org with\n\n    anaconda search -t conda state\n\n(and similarly for the other packages)\n\nYou may need to install the anaconda-client command line client with\n\n    conda install anaconda-client", "stdout": "Fetching package metadata .........\nSolving package specifications: .", "stdout_lines": ["Fetching package metadata .........", "Solving package specifications: ."], "warnings": []}
failed: [test.calpolydatascience.org] (item=ipywidgets=5) => {"changed": true, "cmd": ["conda", "install", "name=ipywidgets=5", "state=present"], "delta": "0:00:04.732561", "end": "2017-01-03 23:47:21.729590", "failed": true, "item": "ipywidgets=5", "rc": 1, "start": "2017-01-03 23:47:16.997029", "stderr": "Error: Packages missing in current linux-64 channels: \n  - name ipywidgets 5\n  - state present*\n\nClose matches found; did you mean one of these?\n\n    state: statsd, static\n\nYou can search for packages on anaconda.org with\n\n    anaconda search -t conda state\n\n(and similarly for the other packages)\n\nYou may need to install the anaconda-client command line client with\n\n    conda install anaconda-client", "stdout": "Fetching package metadata .........\nSolving package specifications: .", "stdout_lines": ["Fetching package metadata .........", "Solving package specifications: ."], "warnings": []}

@minrk @willingc I am going to try to debug, but not sure exactly where to start. The thing that is weird is that conda works fine for these packages if I log in an run it. I have also tried updating the versions.

Update cookie secret in docs

Once the changes re: cookie_secret are made in JupyterHub. Add the change here too.

Letsencrypt auto renew

Hi,

I have been running this setup for a while now and it was time for the letsencrypt certificates to auto renew.

However i get the following error:

All renewal attempts failed. The following certs could not be renewed:
  /etc/letsencrypt/live/[hostname_removed]/fullchain.pem (failure)
1 renew failure(s), 0 parse failure(s)
Thu Jun 22 07:35:02 CEST 2017
Saving debug log to /var/log/letsencrypt/letsencrypt.log
Cert is due for renewal, auto-renewing...
Renewing an existing certificate
Performing the following challenges:
tls-sni-01 challenge for [hostname_removed]
Cleaning up challenges
Attempting to renew cert from /etc/letsencrypt/renewal/[hostname_removed].conf produced an unexpected error: Could not bind TCP port 443 because it is already in use by another process on this system (such as a web server). Please stop the program in question and then try again.. Skipping.

In the letsencrypt renew file that is within cron.daily it seems to have a command with docker. I assume this is a mistake?

#!/usr/bin/env bash

date >> /var/log/letsencrypt.log
certbot-auto renew --no-self-upgrade 2>&1 &>> /var/log/letsencrypt.log
docker kill -s HUP nginx

Review README and install docs

Now that @minrk's #28 has been merged, the README and install docs should be reviewed for accuracy.

Add configuration of JupyterHub groups and shared notebook servers

Jupyterhub now supports having single user notebook servers run as JupyterHub services and giving a group of users access to those servers. It would be great if we offered the configuration of those things in this ansible setup. Here are the examples that show how it can be done:

https://github.com/jupyterhub/jupyterhub/tree/master/examples/service-notebook

We would need:

• List of groups and users in each group
• List of shared servers, with the name of each server (URL) and the group that should be given access.

@minrk @willingc

Spawn error, but service starts

I get a spawn error when restarting jupyterhub:

$ sudo supervisorctl restart jupyterhub
jupyterhub: stopped
jupyterhub: ERROR (spawn error)

Even though I get this error, JupyterHub is started successfully; this is also evident from the logs. So what is this error all about?

jupyterhub.log.txt

Failed Ansible Install Step: restart jupyterhub with supervisor

When installing on UBUNTU Ansible goes through 63 steps successfully but then fails at the step below.

TASK [jupyterhub : restart jupyterhub with supervisor] *************************
fatal: [notebooks.analyticsdojo.com]: FAILED! => {"changed": false, "failed": true, "msg": "jupyterhub: stopped\njupyterhub: ERROR (spawn error)\n"}

NO MORE HOSTS LEFT *************************************************************

RUNNING HANDLER [common : restart ntp] *****************************************

RUNNING HANDLER [nginx : reload nginx] *****************************************
[WARNING]: Could not create retry file 'deploy.retry'. [Errno 2] No such file or directory: ''

PLAY RECAP *********************************************************************
notebooks.analyticsdojo.com : ok=63 changed=54 unreachable=0 failed=1

I've tried multiple times but haven't been able to get past this step.

Best,
Jason

Migrate structure from CP data301

@ellisonbg's enhancements with Makefile and consolidating the configuration parameters to essentially one file greatly simplifies the installation process.

• Migrate Makefile
• Migrate example configuration file for testing

cannot install superviser

ansible failed when installing supervisor

TASK [jupyterhub : restart jupyterhub with supervisor] *************************
fatal: [jupyter.acg.maine.edu]: FAILED! => {"changed": false, "failed": true, "msg": "jupyterhub: stopped\njupyterhub: ERROR (spawn error)\n"}

RUNNING HANDLER [nginx : reload nginx] *****************************************
    to retry, use: --limit @deploy.retry

The log file on the server side

root@jupyter:~# tail /var/log/jupyterhub/jupyterhub.log 
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin
SUPERVISOR_GROUP_NAME=jupyterhub
PWD=/srv/jupyterhub
LANG=en_US.UTF-8
SUPERVISOR_ENABLED=1
SHLVL=1
SUPERVISOR_PROCESS_NAME=jupyterhub
SUPERVISOR_SERVER_URL=unix:///var/run/supervisor.sock
_=/usr/bin/env
/srv/jupyterhub/start-jupyterhub.sh: line 4: exec: jupyterhub: not found

but jupyterhub could be found

root@jupyter:~# which jupyterhub
/opt/conda/bin/jupyterhub

Then, I checked that the PATH variable in the login shell is correct and has /opt/conda/bin. Perhaps, supervisor may have overwritten the PATH variable using sudo!?

root@jupyter:~# echo $PATH
/opt/conda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
root@jupyter:~# sudo -i bash -l -c 'echo $PATH'
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin

Update documentation

Based on feedback from @ellisonbg's experience with CP deployment, we should update the README and Sphinx docs.

• Simplify README moving most installation instructions to Sphinx docs
• Add some UI screenshots to README
• Add a checklist for pre-deployment tasks
  - Obtain domain name
  - ssh key creation
  - DNS routing for server and domain name
  - encourage letsencrypt (which is working well with current Ansible scripts)
• Add user friendly walkthrough of consolidated configuration file and suggested settings

Python 2 On JupyterHub-Teaching

Good morning,

I am trying to deploy a JupyterHub teaching server and I have not found any problems so far. However, as I have seen, I can only use Python 3 kernels, and I was wondering if there is a way to install Python 2 so it can be used to.

Regards.

Tag a release?

I think it would be useful to tag a release once the current open issues are resolved.
This way users know what version of this ansible deployment worked on their platform more easily.

What do you think?

Can this be simpler (esp. use local AuthN instead of github)?

Thanks for this resource!

What would a variant of this procedure look like, that uses local (PAM?) AuthN rather than github? Or, is using github actually easier?

I currently have a vserver set up for classes on which I'm running RStudio Server. Works nicely, but not as flexible as I'd like and obviously not Jupyter. I'd like to extend our offerings on that server rather than start new.

nbgrader

Hi,

I seem to be running into an issue when I try enabling nbgrader for this deployment.

In the jupyterhub log O get:

[I 2017-03-20 16:31:46.722 JupyterHub service:220] Starting service 'formgrade-course1': ['nbgrader', 'formgrade']
[I 2017-03-20 16:31:46.723 JupyterHub service:90] Spawning nbgrader formgrade
[FormgradeApp | WARNING] Outdated config: use Exchange.course_id rather than NbGrader.course_id
[FormgradeApp | WARNING] Config option `port` not recognized by `FormgradeApp`.
[FormgradeApp | WARNING] Config option `authenticator_class` not recognized by `FormgradeApp`.
[FormgradeApp | WARNING] Config option `ip` not recognized by `FormgradeApp`.
[FormgradeApp | ERROR] The formgrader is no longer a standalone command, but is
    rather an extension that is part of the Jupyter notebook. To run the
    formgrader, make sure you have enabled the nbgrader server extensions:

    http://nbgrader.readthedocs.io/en/stable/user_guide/installation.html#nbgrader-extensions

    Then, run the notebook from the command line as normal:

        $ jupyter notebook

    And click on the "Formgrader" tab in the window that opens.
[E 2017-03-20 16:32:16.726 JupyterHub service:250] Service formgrade-course1 exited with status 1

Update docs to reflect changes in PR #10 and #11

Review PR #10 and #11 for necessary doc changes.

Cannot find file `deploy_formgrade.yml`.

First, thank you for creating this repository.

I set up an instance of JupyterHub on a Linode instance.

I have successfully started JupyterHub, and I am able to log in as an admin.

I want to use nbgrader and am blocked at the Deploy formgrade section.

I cannot find an example of the deploy_formgrade.yml file to edit, and don't know how or if I am supposed to create it.

And I don't know if nbgrader is installed or how to use it.

Thank you in advance for your suggestions on how to continue.

Update License File

Anaconda path issue

I am testing on Ubuntu 16.04, I use the ubuntu as user and root as become_user.
the playbook sets the path to anaconda in /opt/conda/bin systemwide, in fact when I login either with root or ubuntu, it works fine.

However all tasks in the playbook that require anaconda fail. I fixed adding:

 environment:
    PATH: "/opt/conda/bin:{{ ansible_env.PATH }}"

to all tasks, but there must be a better way.
BTW cannot do at playbook level because ansible_env.PATH is undefined.

Any suggestion?

cull_idle_server.conf

It seems that --url=http://... is missing from cull_idle_servers.conf.j2

or appropriate env. variable is not there

mk

Start to tag releases that follow jupyterhub versions

After trying to get everything in this repo working well with jupyterhub 0.7.0, I think we should start to tag/release versions of this repo that follow the versions of jupyterhub. That will make it much easier for folks to know and understand which version of this repo are known to work with which versions of jupyterhub/nbgrader/etc.

@minrk @willingc @jhamrick

deploy_formgrade fails

nbgrader exits with (in logs):

Traceback (most recent call last):
File "/opt/conda/lib/python3.5/site-packages/traitlets/traitlets.py", line 526, in get
value = obj._trait_values[self.name]
KeyError: 'hub_authenticator'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "/opt/conda/lib/python3.5/site-packages/traitlets/traitlets.py", line 526, in get
value = obj._trait_values[self.name]
KeyError: 'hubapi_base_url'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "/opt/conda/bin/nbgrader", line 9, in
load_entry_point('nbgrader', 'console_scripts', 'nbgrader')()
File "/tmp/src/nbgrader/nbgrader/apps/nbgraderapp.py", line 258, in main
NbGraderApp.launch_instance()
..............................

config-http-proxy not installing

With a fresh deployment, I get an error:

[I 2016-10-02 15:50:13.731 JupyterHub app:624] Loading cookie_secret from /srv/jupyterhub/cookie_secret
[I 2016-10-02 15:50:13.819 JupyterHub app:1232] Hub API listening on http://127.0.0.1:8081/hub/
[W 2016-10-02 15:50:13.822 JupyterHub app:960] Running JupyterHub without SSL. There better be SSL termination happening somewhere else...
[I 2016-10-02 15:50:13.822 JupyterHub app:969] Starting proxy @ http://65.61.190.162:8000/
[E 2016-10-02 15:50:13.824 JupyterHub app:977] Failed to find proxy ['configurable-http-proxy']
    The proxy can be installed with `npm install -g configurable-http-proxy`

Running conda list does not show the configurable-http-proxy package.

@minrk @willingc any ideas?

404 on server reboot on Formgrader tab.

I am getting a 404 page not found in the Formgrader tab after reboot.

I deployed to Ubuntu 16.04.3 LTS via ansible ($ ansible-playbook deploy.yml).

The versions of each component that were installed are as follows:

$ jupyterhub --version

0.7.0

$ jupyter --version

4.3.0

$ nbgrader --version

Python version 3.5.2 |Continuum Analytics, Inc.| (default, Jul 2 2016, 17:53:06)

[GCC 4.4.7 20120313 (Red Hat 4.4.7-1)]

nbgrader version 0.6.0.dev

Let me know anything else that you might need.