Jupyterhub 安装指南

Jupyter notebook 是一款很好用的在线开发 python 工具，不过它原生只能单用户使用，没有多用户登录功能。而 Jupyterhub 就是为解决这个问题而开发的。

参考：

https://nodejs.org/en/download/package-manager/

https://github.com/nodesource/distributions/blob/master/README.md

对于 debian 系的操作系统，推荐使用源安装：

# 添加源，以下版本选择一个即可。
# Node.js v12.x:
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
# Node.js v11.x:
curl -sL https://deb.nodesource.com/setup_11.x | sudo -E bash -
# Node.js v10.x:
curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
 
# 安装
sudo apt-get update
sudo apt-get install nodejs

jupyterhub 支持 docker 部署，这块后续可以尝试，下面以传统的方式进行安装。

安装比较简单，直接使用 pip 和 npm 安装即可：

python3 -m pip install jupyterhub
npm install -g configurable-http-proxy
 
# nodeboot 可选
python3 -m pip install notebook

安装完成后，直接运行 jupyterhub 即可启动。

配置 jupyterhub 既可以直接在命令后面加参数，也可以直接写一个 python 格式的配置文件 jupyterhub_config.py ，其中配置文件中的配置项都要以 c. 开头。

使用以下命令在当前目录 /etc/jupyterhub 目录下生成一个默认的配置文件 jupyterhub_config.py ：

jupyterhub --generate-config -f /etc/jupyterhub/jupyterhub_config.py

使用以下命令运行 jupyterhub 并加载配置文件：

jupyterhub -f /etc/jupyterhub/jupyterhub_config.py

Jupyterhub 使用 Authenticators 接口进行用户验证，默认使用的是 PAM ，即系统自己的用户。

可用的 Authenticators 列表可以参考： https://github.com/jupyterhub/jupyterhub/wiki/Authenticators

这里使用的是 LDAP Authenticator。

pip install jupyterhub-ldapauthenticator

在配置文件中添加：

# 指定 authenticator 使用的类
c.JupyterHub.authenticator_class = 'ldapauthenticator.LDAPAuthenticator'
 
# 配置 LDAP 信息，这里是与 windows AD 集成。
c.LDAPAuthenticator.server_address = '192.168.0.254'
c.LDAPAuthenticator.bind_dn_template = ['cn={username},OU=yourou,DC=example,DC=com']
c.LDAPAuthenticator.use_ssl = True
c.LDAPAuthenticator.lookup_dn = True
c.LDAPAuthenticator.lookup_dn_search_filter = '({login_attr}={login})'
c.LDAPAuthenticator.lookup_dn_search_user = 'CN=test,ou=yourou,dc=example,dc=com'
c.LDAPAuthenticator.lookup_dn_search_password = 'xxxxxxxx'
c.LDAPAuthenticator.user_search_base = 'ou=yourou,dc=example,dc=com'
c.LDAPAuthenticator.user_attribute = 'sAMAccountName'
c.LDAPAuthenticator.lookup_dn_user_dn_attribute = 'cn'
c.LDAPAuthenticator.escape_userdn = False

更多配置参考： https://github.com/jupyterhub/ldapauthenticator

Jupyterhub 使用 Spawners 接口运行单个用户的 notebook 环境。

可用的 Spawners 列表可以参考： https://github.com/jupyterhub/jupyterhub/wiki/Spawners

这里使用的是 DockerSpawner。即每个用户登录之后，系统会启动独立的 docker 环境运行该用户的 notebook 。

pip install dockerspawner

在配置文件中添加：

# 指定 spawner 使用的类
c.JupyterHub.spawner_class = 'dockerspawner.DockerSpawner'
 
# 配置 docker 容器的 host_ip
c.DockerSpawner.host_ip = "0.0.0.0"
 
# 由于 docker 内的 notebook 需要与 jupyterhub 进行通信，这里推荐给 jupyterhub 指定一个 ip ，否则 docker 无法找到 jupyterhub 。
c.JupyterHub.hub_ip = '192.168.0.250'

更多配置参考： https://github.com/jupyterhub/dockerspawner

默认情况下， DockerSpawner 使用的镜像是 jupyterhub/singleuser ， 如需要指定其他镜像，则使用类似配置：

c.DockerSpawner.image = 'jupyter/scipy-notebook:8f56e3c47fec'

注意，自定义镜像必须：

1. Python >= 3.4
2. 安装了 JupyterHub
3. 安装了 jupyter notebook
4. 使用 CMD [“jupyterhub-singleuser”] 启动

docker 容器无法保存数据，故需要类似以下配置进行数据持久化：

# 原镜像使用的用户是 jovyan ，故这里可以固定用户。
notebook_dir = '/home/jovyan/work'
c.DockerSpawner.notebook_dir = notebook_dir
c.DockerSpawner.volumes = { 'jupyterhub-user-{username}': notebook_dir }

jupyter-lab 是下一代 jupyter ，提供全新的 ui 。

安装

pip install jupyterlab

配置。 jupyter-lab 使用新的地址 /lab ， 旧的地址是 /tree ， 两者之间可以手动切换。 如果希望 jupyterhub 默认打开 jupyterlab 的地址，则修改配置：

c.Spawner.default_url = '/lab'

https://github.com/jupyterhub/jupyterhub/wiki/Run-jupyterhub-as-a-system-service

创建文件： /etc/systemd/system/jupyter.service

[Unit]
Description=Jupyterhub
After=syslog.target network.target
 
[Service]
User=root
WorkingDirectory=/var/local/jupyterhub
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/usr/local/bin/jupyterhub -f /etc/jupyterhub/jupyterhub_config.py
 
[Install]
WantedBy=multi-user.target

然后执行命令：

sudo systemctl daemon-reload
sudo systemctl <start|stop|status> jupyterhub
 
# 设置开机运行
sudo systemctl enable jupyterhub

参考资料： https://github.com/jupyterhub/jupyterhub/issues/1219

在使用 ldap 的方式登录时，可能系统内还没有用户的 home 目录，这时 jupyter 可能会启动失败。

解决方法： 编辑 /etc/jupyterhub/jupyterhub_config.py 文件，加上以下配置。

from subprocess import check_call
def my_spawn_hook(spawner):
    username = spawner.user.name
    check_call(['mkhomedir_helper', username, '0077'])
 
c.Spawner.pre_spawn_hook = my_spawn_hook