tanbro/单机多用户 JupyterLab 环境搭建.md

## 单机多用户 JupyterLab 环境搭建.md

      
    Raw
  

              单机多用户 JupyterLab 环境搭建.md
            
          
    单机多用户 JupyterLab 环境搭建

概述

在这篇短文中，我们记录了如何在使用 Ubuntu 1804 LTS 操作系统的单台服务器上，建立用户隔离的 JupyterLab Web 环境。
目标是：

操作系统的用户可以各自不受干扰的使用独立的 JupyterLab
各个用户的 Conda 环境可以自动的出现在 JupyterLab 的 Kernel 列表中
每个用户都可以新建自己的 Conda 或者 venv 环境，并在其中安装 Conda 或 pip 软件
可以在 notebook 中使用本机的 NVIDIA GPU

准备工作


为服务器安装 Ubuntu 1804 长期支持版。
如果需要使用 NVIDIA GPU，建议安装带有完整图形界面的桌面版操作系统，以简化配置。


确保服务器可以连接到互联网


更新服务器上的软件包，在终端执行:
sudo apt update
sudo apt upgrade --auto-remove


如果需要使用 NVIDIA GPU，应安装其驱动。

ℹ 说明:

由于我们准备在 Conda 环境中安装配置 Jupyter Kernel ，故仅安装 Driver，而不在操作系统级别安装 CUDA、cuDNN 等软件包。
推荐的方式是：各用户自行在各个环境中使用 Conda 分别安装这些软件包。
NVIDIA 官方网站提供的 Driver 安装过程比较繁琐，涉及到 Linux 的 modprobe 与 initramfs 的修改，本文不予记载。
所采用的 NVIDIA Driver 版本应根据操作系统版本、 Graphic 设备和 CUDA 版本要求决定。具体应参考 NVIDIA 网站说明。


本文中，我们使用 Apt 安装 NVIDIA Driver 最新的长期支持版（以430为例）:

ℹ 提示:
我们可通过 https://www.nvidia.com/object/unix.html 获知 Unix 驱动的版本支持信息


字符界面安装
sudo add-apt-repository restricted
sudo apt-get update
sudo apt-get install nvidia-driver-430


图形界面安装

打开 “软件和更新” 系统应用
在该应用的 “Ubuntu 软件” 选项卡中，选中 "设备的专有驱动(restricted)" 选项
在该应用的 “附加驱动” 选项卡中，待 “搜索可用驱动” 完毕后，选择 NVIDIA Corporation 下最新的长期支持版驱动版本


安装和配置 JupyterHub

安装 JupyterHub

我们将在操作系统级安装 JupyterHub，并以 root 身份运行该软件，以便启停其它账户的 JupyterLab 进程。
JupyterHub 在启动时执行 configurable-http-proxy 进程，用它来反向代理目标用户 JupyterLab 的 HTTP 通信。不过，它无法配置 configurable-http-proxy 的路径。
所以，我们还需要在操作系统级安装 configurable-http-proxy。


安装 JupyterHub
这是一个 Python 程序，且没有官方 Apt 源。所以，我们用 pip 安装。


apt 安装 Python 和 pip:
sudo apt install python3 python3-pip


使用 pip 安装 JupyterHub，注意要在操作系统级安装：
sudo -H pip3 install -U jupyterhub


安装 configurable-http-proxy
这是一个 Node.js 程序，且没有官方 Apt 源。所以，我们用 npm 安装。


apt 安装 Node.js 和 npm:
sudo apt install nodejs npm


npm 安装 configurable-http-proxy，注意要在操作系统级安装：
sudo npm install -g configurable-http-proxy


配置 JupyterHub

我们采用 JupyterHub 默认的 single-user 模式，其登录用户就是操作系统的账户。
但是，为了实现我们的需求，还需修改配置文件，让 JupyterHub 登录进入用户的 shell 之后，以目标用户的身份执行 jupyterhub-singleuser 进程，而不是直接在当前进程的环境中直接启动。


生成默认配置文件
生成默认配置文件 jupyterhub_config.py，将它移动到系统目录，如 /etc/jupyterhub，并重命名为 config.py:
jupyterhub --generate-config
sudo mkdir -p /etc/jupyterhub
sudo cp jupyterhub_config.py /etc/jupyterhub/config.py


修改配置文件


修改 single-user-spawner 的默认启动方式（必须）
这是最为重要的一个步骤！
我们通过该设置，让 JupyterHub 以目标用户的身份登录 bash，然后运行 jupyterhub-singleuser，由这个进程此启动用户环境中的 JupyterLab。
c.LocalProcessSpawner.shell_cmd = ["bash", "-l", "-c"]


使用 JupyterLab 而非 Jupyter notebook（可选）
c.Spawner.default_url = "/lab"


设置 JupyterHub Web 服务的 HTTP 地址（可选）。应根据实际网络规划设置，如：
c.JupyterHub.ip = "0.0.0.0"


不用确保运行 JupyterLab 的环境处于 Kenerl 在列表中（可选）
c.Spawner.args = ["--KernelSpecManager.ensure_native_kernel=False"]


后台运行 JupyterHub

编辑以下文本到 systemd 配置文件 jupyterhub.service
[Unit]
Description=Jupyterhub service
After=syslog.target network.target

[Service]
ExecStart=/usr/local/bin/jupyterhub -f /etc/jupyterhub/config.py

[Install]
WantedBy=multi-user.target
然后将它复制到 systemd 系统配置目录，并修改权限：
sudo cp jupyterhub.service /etc/systemd/system
sudo chmod 644 /etc/systemd/system/jupyterhub.service
最后，刷新服务列表并启动该服务：
sudo systemctl daemon-reload
sudo systemctl start jupyterhub
如果需要该服务自动运行，执行：
sudo systemctl enable jupyterhub
进程调用关系示意图

digraph G {
   graph [
      label="进程调用关系示意图"
   ];
   browser [shape=box, color=blue];
   hub [label="root:/usr/loca/bin/jupyterhub", color=red];
   proxy [label="root:/usr/local/bin/configurable-http-proxy", color=red];
   bash [label="root: sudo -u USER -i bash -l -c 'jupyterhub-singleuser'", color="lightblue"];
   user [label="USER:jupyterhub-singleuser", color=yellowgreen];
   lab [label="USER:jupyter-lab", color=green];
   kernel  [label="USER:<path/of/installed/kernel/>python", color=green];
   browser -> proxy -> lab [label=http, color=blue];
   browser -> kernel [style=dashed, color=gray];
   hub -> proxy [label=subprocess];
   hub -> bash -> user -> lab -> kernel [label=subprocess];
}
![进程调用关系示意图](https://g.gravizo.com/svg?digraph G {
graph [
label="进程调用关系示意图"
];
browser [shape=box, color=blue];
hub [label="root:/usr/loca/bin/jupyterhub", color=red];
proxy [label="root:/usr/local/bin/configurable-http-proxy", color=red];
bash [label="root: sudo -u USER -i bash -l -c 'jupyterhub-singleuser'", color="lightblue"];
user [label="USER:jupyterhub-singleuser", color=yellowgreen];
lab [label="USER:jupyter-lab", color=green];
kernel  [label="USER:<path/of/installed/kernel/>python", color=green];
browser -> proxy -> lab [label=http, color=blue];
browser -> kernel [style=dashed, color=gray];
hub -> proxy [label=subprocess];
hub -> bash -> user -> lab -> kernel [label=subprocess];
})
用户环境

每个操作系统的普通用户，都可以使用 JupyterHub 的 Web 界面，通过操作系统用户名和密码登录到用户隔离的 JupyterLab 进程。
但是，在此之前，我们还需要为这些用户安装软件、修改配置。
本章节中记录的后续操作，均假定已使用目标用户身份登录。
安装 Conda

首先，为这个用户安装 Conda。为了安装配置过程的轻便，我们在本例中采用 Miniconda 而非 Anaconda。
执行：
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
然后按照提示，使用默认值进行安装。
当安装程序输出下面的提示时：
installation finished.
Do you wish the installer to initialize Miniconda3
by running conda init? [yes|no]
[no] >>>
输入 yes
安装完成后，执行以下命令或者重新登录：
source ~/.bashrc
在 Conda base 环境中安装必备软件

在 Conda base 环境中安装 Jupyter, JupyterLab, JupyterHub, nb_conda 等相关软件包，推荐使用 conda-forge 通道：
conda install -n base  -c conda-forge jupyter jupyterlab jupyterhub nb_conda widgetsnbextension
完成后，安装 JupyterLab 的 Web 扩展 jupyterlab-manager (可选)：
jupyter labextension install @jupyter-widgets/jupyterlab-manager
修改 ~/.profile 配置文件

我们还需要将 Conda base 环境的 bin 目录加到 PATH 环境变量。
这是因为，我们修改了 JupyterHub 的配置，并让不同用户使用各种环境中不同路径的 jupyterhub-singleuser；而 JupyterHub 的 SingleUserSpawner 在登录目标用户 bash 并执行 jupyterhub-singleuser 时，以及 jupyterhub-singleuser 执行 JupyterLab 时， 均无法指定路径。
为此，我们将在该用户的 Conda base 环境下安装 JupyterHub 和 JupyterLab ，且需确保 JupyterHub 的 SingleUserSpawner 在登录该用户的 bash 时将上述 base 环境的执行目录自动加入到 PATH 环境变量。
这样，SingleUserSpawner 和 jupyterhub-singleuser 就可以搜索到执行文件了。
我们可以修改 ~/.profile 配置，使得 JupyterHub 登录到该用户的 bash 时，PATH 被修改。
方法是：


在 ~/.profile 的末尾加上：
PATH="/home/USER/miniconda3/bin:$PATH"
其中 USER 表示用户名；如果使用的是 anaconda，目录会有所不同。应根据实际情况设置。


也可用以下 shell 脚本在 ~/.profile 的最后一行添加上述内容：
echo "PATH=\"$(dirname $CONDA_EXE):\$PATH\"" | tee -a ~/.profile


新建 Jupyter Kernel

Conda 环境自动添加到 Kernels 列表

如果在用户的 Conda 环境安装 ipython 与 nb_conda，nb_conda 会自动在Jupyter(其所在环境也需要安装 nb_conda) 的 Kernels 列表中添加其所在的环境。
例如，新建一个名为 myenv 的环境，在这个环境安装 ipython 和 nb_conda，刷新页面，就可以在Kenerls列表中看到这个环境了。
新建这样一个环境，命令是：
conda create -n myenv ipython nb_conda ipywidgets
对于已经存在的 Conda 环境，可以随时安装 ipython 与 nb_conda。一旦安装，即可被 JupyterLab（中的 nb_conda）检测到。
手动添加 Python 环境到 Kernels 列表

任何 Python 环境，无论是系统级、用户级、venv 还是 Conda 环境，凡是安装了 ipython 软件包的，都可以手动添加到 Jupyter 的 Kernels 列表。
方法是在激活的目标环境中执行：
python -m ipykernel install --user --name="myenv" --display-name="My environment"
具体参考： https://ipython.readthedocs.io/en/stable/install/kernel_install.html
安装软件包


⚠ 警告:
为了防止 base 环境被意外破坏，我们不应在 base 环境中进行工作或者安装/删除/修改软件包。
推荐的方式是：为每项工作单独维护一个 Conda 环境。

使用 Conda 安装

常规的方法是通过终端使用  conda 命令指定或者激活目标环境后进行安装。
也可以在 Jupyter 笔记本中，使用“魔术方法”安装，如： %conda install tqdm

ℹ 注意:
%conda 所使用的 Conda 环境 与笔记正在使用的 Kernel 的是一致的。
为保险起见，可执行 %conda env list 查看。

使用 pip 安装

常规的方法是通过终端切激活目标环境，然后使用  pip 命令进行安装。
也可以在 Jupyter 笔记本中，使用“魔术方法”安装，如： %pip install tqdm

ℹ 注意:
%pip 所使用的环境与笔记正在使用的 Kernel 的是一致的。
为保险起见，可执行 %pip --version 查看。

实例

新建用户环境

在这个实例中，我们新建一个操作系统用户，使用 JupyterHub Web GUI，以该用户身份登录；并且在这个用户名下新建一个 Conda 环境，让 JupyterLab 自动将该环境加入到其 Kernels 列表。


新建用户
假定用户名为 {{USER}}:
sudo adduser {{USER}}


为新建的用户安装 Conda
以上一步骤中新建的 {{USER}} 身份登录。为了提高网速，建议使用清华大学 Anaconda 镜像：


下载 Miniconda：
wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-x86_64.sh


安装 Miniconda（参考 安装 Conda 一节）：
bash Miniconda3-latest-Linux-x86_64.sh


更新 bash 环境：
source .bashrc


修改环境变量 PATH 和  Conda 配置


修改用户配置文件中的搜索路径环境变量：
echo "PATH=\"$(dirname $CONDA_EXE):\$PATH\"" >> ~/.profile


修改 Conda 的用户配置文件 ~/.condarc，设置清华大学 Anaconda 镜像：
channels:
  - defaults
show_channel_urls: true
default_channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
custom_channels:
  conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud


base 环境安装 jupyter, jupyterlab, jupyterhub, nb_conda 等软件包（推荐使用 conda-forge 通道）：
conda install -n base jupyter jupyterlab jupyterhub nb_conda widgetsnbextension -c conda-forge


安装 JupyterLab 的 几个常用 Web 扩展（可选）：
jupyter-labextension install @jupyter-widgets/jupyterlab-manager @jupyterlab/toc


新建 Conda 环境，安装软件包

不建议在 base 环境中直接进行工作，以避免破坏运行 JupyterHub 与 JupyterLab 的基础环境。
所以，我们一般会为每一项工作单独新建一个 Conda 环境。


新建 Conda 环境
新建的环境如果具有软件包 ipython 和 nb_conda，就可以被 Jupyter (其所在环境也需要安装 nb_conda)自动检测到。
此处，我们新建一个名为 mypy36、使用 Python 3.6 的环境为例：
conda create --name mypy36 python=3.6 ipython nb_conda ipywidgets
等一小会儿，查看页面，这个环境是不是已经出现在 Kernels 列表中了？


安装软件包。
下面，我们在这个环境中安装一个软件包。例如，我们想要安装 pandas：
在 JupyterLab 的 Notebook 的代码 cell 中，或者 Console 的命令输入框中，使用魔法命令 %conda 或者 %pip 安装。该软件包会安装到该 Notebook 或者 Console 所使用的 Kernel 对应环境中。


Conda 安装(在笔记的 Cell 中执行)
%conda install pandas


pip 安装(在笔记的 Cell 中执行)
%pip install pandas


此外，也可以通过终端，直接使用 conda 或者 pip 命令行安装。安装时注意不要搞错环境。

❗ 重要:
对于类似于 tensorflow-gpu 这样依赖复杂的大型第三方 C/C++ libraries（它依赖 CUDA, cuDNN）、构建复杂、且其 wheel 包无法提供完整预编译库/可执行文件的软件包，建议使用 Conda 进行安装。这样可以简便的解决库依赖和环境隔离问题，避免从源代码编译。


ℹ 提示:
如果 pip 以及 conda 官方源镜像的网络条件不好，可以考虑使用国内的镜像。

pypi 镜像推荐:

https://opsx.alibaba.com/mirror
http://mirrors.163.com/.help/pypi.html
https://mirror.tuna.tsinghua.edu.cn/help/pypi/


Conda 镜像推荐：

https://mirror.tuna.tsinghua.edu.cn/help/anaconda/