magicalion/singleuser-job

Base Jupyter Notebook Stack

用于定义自定义栈的小型基础镜像

核心功能与特性

• 功能最小化的Jupyter Notebook 5.2.x（例如，无pandoc文档转换工具）
• Miniconda Python 3.x环境
• 无预安装的科学计算包
• 无特权用户jovyan（uid=1000，可配置，见选项），属于users组（gid=100），拥有/home/jovyan和/opt/conda目录的所有权
• 使用https://github.com/krallin/tini%E4%BD%9C%E4%B8%BA%E5%AE%B9%E5%99%A8%E5%85%A5%E5%8F%A3%E7%82%B9%EF%BC%8Cstart-notebook.sh%E4%BD%9C%E4%B8%BA%E9%BB%98%E8%AE%A4%E5%91%BD%E4%BB%A4
• 提供start-singleuser.sh脚本，用于运行Notebook服务器的单用户实例（JupyterHub所需）
• 提供start.sh脚本，用于在容器中运行替代命令（如ipython、jupyter kernelgateway、jupyter lab）
• 支持自签名HTTPS证书和无密码sudo选项

使用场景

适合作为构建自定义Jupyter环境的基础，尤其适用于需要根据特定需求定制Python环境、安装额外科学计算包或集成其他Jupyter应用的场景。可作为数据科学、机器学习项目的基础开发环境。

使用方法

基本使用

以下命令启动一个容器，Notebook服务器在8888端口监听HTTP连接，并配置随机生成的身份验证令牌。

bash
docker run -it --rm -p 8888:8888 jupyter/base-notebook

注意 notebook启动日志中包含的身份验证令牌，访问Notebook服务器时需在URL中包含该令牌或在登录表单中输入。

Notebook选项

Docker容器默认执行start-notebook.sh脚本。该脚本处理下一节文档中所述的NB_UID、NB_GID和GRANT_SUDO特性，然后执行jupyter notebook。

可通过设置JUPYTER_ENABLE_LAB启动https://github.com/jupyterlab/jupyterlab%EF%BC%9A

bash
docker run -it --rm -e JUPYTER_ENABLE_LAB=1 -p 8888:8888 jupyter/base-notebook

启动容器时，可通过start-notebook.sh脚本传递Jupyter命令行选项。例如，使用IPython.lib.passwd()生成的自定义密码哈希（而非默认令牌）保护Notebook服务器：

bash
docker run -d -p 8888:8888 jupyter/base-notebook start-notebook.sh --NotebookApp.password='sha1:74ba40f8a388:c913541b7ee99d15d5ed31d4226bf7838f83a50e'

例如，设置notebook服务器的基础URL：

bash
docker run -d -p 8888:8888 jupyter/base-notebook start-notebook.sh --NotebookApp.base_url=/some/path

例如，禁用所有身份验证机制（不推荐）：

bash
docker run -d -p 8888:8888 jupyter/base-notebook start-notebook.sh --NotebookApp.token=''

也可绕过start-notebook.sh脚本，在容器中运行自定义命令，详见本文档后面的"替代命令"部分。

Docker选项

可通过以下可选参数自定义Docker容器的执行及其运行的命令：

• -e GEN_CERT=yes - 生成自签名SSL证书，并配置Jupyter Notebook使用该证书接受加密HTTPS连接。
• -e NB_UID=1000 - 指定jovyan用户的uid。用于挂载具有特定文件所有权的主机卷时。要使此选项生效，必须以--user root运行容器（start-notebook.sh脚本会在调整用户ID后执行su jovyan）。
• -e NB_GID=100 - 指定jovyan用户的gid。用于挂载具有特定文件所有权的主机卷时。要使此选项生效，必须以--user root运行容器（start-notebook.sh脚本会在调整组ID后执行su jovyan）。
• -e GRANT_SUDO=yes - 赋予jovyan用户无密码sudo权限。用于安装OS包时。要使此选项生效，必须以--user root运行容器（start-notebook.sh脚本会在将jovyan添加到sudoers后执行su jovyan）。仅当信任用户或容器运行在隔离主机上时，才应启用sudo。
• -v /some/host/folder/for/work:/home/jovyan/work - 将主机目录挂载为容器中的文件夹。用于在容器销毁后保留notebook和其他工作。必须授予容器内notebook用户或组（NB_UID或NB_GID）对主机目录的写权限（例如sudo chown 1000 /some/host/folder/for/work）。
• --group-add users - 当指定特定用户ID启动容器（-u 5000）而非以root身份启动并依赖NB_UID和NB_GID设置用户和组时，使用此参数。

SSL证书

可将SSL密钥和证书文件挂载到容器中，并配置Jupyter Notebook使用它们接受HTTPS连接。例如，挂载包含notebook.key和notebook.crt的主机文件夹：

bash
docker run -d -p 8888:8888 \
    -v /some/host/folder:/etc/ssl/notebook \
    jupyter/base-notebook start-notebook.sh \
    --NotebookApp.keyfile=/etc/ssl/notebook/notebook.key \
    --NotebookApp.certfile=/etc/ssl/notebook/notebook.crt

或者，挂载包含密钥和证书的单个PEM文件：

bash
docker run -d -p 8888:8888 \
    -v /some/host/folder/notebook.pem:/etc/ssl/notebook.pem \
    jupyter/base-notebook start-notebook.sh \
    --NotebookApp.certfile=/etc/ssl/notebook.pem

无论哪种情况，Jupyter Notebook都要求密钥和证书是base64编码的文本文件。证书文件或PEM可包含一个或多个证书（如服务器证书、中间证书和根证书）。

有关使用SSL的更多信息，请参阅：

• https://github.com/jupyter/docker-stacks/tree/master/examples - 了解在公共可见域上运行这些栈时如何使用Let's Encrypt证书。
• jupyter_notebook_config.py文件 - 了解此Docker镜像如何生成自签名证书。
• Jupyter Notebook文档 - 有关运行公共notebook服务器的最佳实践，其中大部分已在本镜像中实现。

Conda环境

默认Python 3.x Conda环境位于/opt/conda。

jupyter、ipython、python、pip和conda等命令在环境中均可用。为方便起见，无论当前激活哪个环境，都可使用以下命令将包安装到任一环境：

bash
# 安装包到默认（python 3.x）环境
pip install some-package
conda install some-package

替代命令

start.sh

start.sh脚本支持与默认start-notebook.sh脚本相同的特性（如GRANT_SUDO），但允许指定任意命令执行。例如，在容器中运行基于文本的ipython控制台：

bash
docker run -it --rm jupyter/base-notebook start.sh ipython

或者，运行JupyterLab而非经典notebook：

bash
docker run -it --rm -p 8888:8888 jupyter/base-notebook start.sh jupyter lab

当从该镜像派生新Dockerfile并安装带有jupyter console、jupyter kernelgateway等子命令的其他Jupyter应用时，此脚本特别有用。

其他命令

可绕过提供的脚本并指定任意启动命令。但请注意，这样做会导致上述某些特性（如GRANT_SUDO）无法正常工作。