Jupyterhub 安装指南

发表于： 更新于： 分类于：
字数： 1138 阅读：≈ 3分钟 浏览： 评论：

Jupyterhub 安装指南

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

一、安装 nodejs （若已安装则跳过）

参考：

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 添加源，以下版本选择一个即可。
# 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

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

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

1
2
3
4
5

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

# nodeboot 可选
python3 -m pip install notebook

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

三、配置 jupyterhub

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

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

1

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

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

1

jupyterhub -f /etc/jupyterhub/jupyterhub_config.py

1. 使用 LDAP 进行登录

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

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

这里使用的是 LDAP Authenticator。

1.1 安装 

1

pip install jupyterhub-ldapauthenticator

1.2 配置

在配置文件中添加：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 指定 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

2. 使用 Docker 运行单个用户的环境

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

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

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

2.1 安装 

1

pip install dockerspawner

2.2 简单配置

在配置文件中添加：

1
2
3
4
5
6
7
8

# 指定 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

2.3 配置自定义镜像

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

1

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

注意，自定义镜像必须：

  • Python >= 3.4
  • 安装了 JupyterHub
  • 安装了 jupyter notebook
  • 使用 CMD [“jupyterhub-singleuser”] 启动

2.4 配置数据持久化

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

1
2
3
4

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

3. 使用 jupyter-lab （非 docker 方式）

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

安装

1

pip install jupyterlab

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

1

c.Spawner.default_url = '/lab'

4. 以系统服务的方式运行

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

[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

然后执行命令：

1
2
3
4
5

sudo systemctl daemon-reload
sudo systemctl <start|stop|status> jupyterhub

# 设置开机运行
sudo systemctl enable jupyterhub

5. 登录时创建用户目录(如果不存在)

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

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

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

1
2
3
4
5
6

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