magicalion/singleuser

基础Jupyter Notebook栈

!docker pulls !docker stars

镜像概述和主要用途

这是一个用于定义自定义Jupyter栈的小型基础镜像。它提供了最基本的Jupyter Notebook环境，适合需要根据自身需求构建定制化数据科学或开发环境的用户。该镜像不包含预安装的科学计算包，为用户提供了一个干净的基础，可灵活添加所需组件。

核心功能和特性

• 功能最小化的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%8C%E9%BB%98%E8%AE%A4%E5%91%BD%E4%BB%A4%E4%B8%BAstart-notebook.sh
• start-singleuser.sh脚本，用于运行Notebook服务器的单用户实例（JupyterHub所需）
• start.sh脚本，用于在容器中运行替代命令（如ipython、jupyter kernelgateway、jupyter lab）
• 支持自签名HTTPS证书和无密码sudo的选项

使用场景和适用范围

• 需要构建自定义Jupyter环境的开发者和数据科学家
• 希望最小化基础镜像大小，仅添加必要组件的场景
• 需要在容器中运行Jupyter Notebook或JupyterLab的场景
• 需集成到JupyterHub作为单用户服务器的场景

详细使用方法和配置说明

基本使用

以下命令启动一个容器，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。

启动JupyterLab

通过设置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

传递Jupyter命令行选项

启动容器时，可通过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后将切换为jovyan用户。）
• -e NB_GID=100 - 指定jovyan用户的gid。用于挂载具有特定文件所有权的主机卷。要使此选项生效，必须以--user root运行容器。（start-notebook.sh脚本在调整组ID后将切换为jovyan用户。）
• -e GRANT_SUDO=yes - 为jovyan用户提供无密码sudo权限。用于安装操作系统包。要使此选项生效，必须以--user root运行容器。（start-notebook.sh脚本在将jovyan添加到sudoers后将切换为jovyan用户。）仅当信任用户或容器运行在隔离主机上时，才应启用sudo。
• -v /some/host/folder/for/work:/home/jovyan/work - 将主机目录挂载为容器中的文件夹。用于在容器销毁后保留笔记本和其他工作。必须授予容器内的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）将无法正常工作。