jupyter/tmpnb

tmpnb，临时笔记本服务

启动“临时”Jupyter笔记本服务器。

警告：tmpnb 已不再积极维护。

建议切换到以下替代方案：

配置选项 1：

• JupyterHub 配合 https://github.com/jupyterhub/tmpauthenticator

配置选项 2：

• BinderHub

镜像概述和主要用途

tmpnb 为每个用户请求启动一个 Docker 容器，实际应用包括提供临时笔记本、作为《自然》文章的 IPython 笔记本演示，甚至http://odewahn.github.io/publishing-workflows-for-jupyter/#1%E3%80%82%E7%94%A8%E6%88%B7%E5%8F%AF%E5%9C%A8%E7%94%A8%E6%88%B7%E7%BB%84%E3%80%81%E8%81%9A%E4%BC%9A%E5%92%8C%E7%A0%94%E8%AE%A8%E4%BC%9A%E4%B8%AD%E4%BD%BF%E7%94%A8%E5%AE%83%EF%BC%8C%E6%97%A0%E9%9C%80%E4%BB%BB%E4%BD%95%E6%9C%AC%E5%9C%B0%E5%AE%89%E8%A3%85%E5%8D%B3%E5%8F%AF%E6%8F%90%E4%BE%9B%E5%AF%B9%E5%AE%8C%E6%95%B4%E7%B3%BB%E7%BB%9F%E7%9A%84%E4%B8%B4%E6%97%B6%E8%AE%BF%E9%97%AE%E3%80%82

快速开始

安装 Docker 后执行以下步骤：

bash
docker pull jupyter/minimal-notebook
export TOKEN=$( head -c 30 /dev/urandom | xxd -p )
docker run --net=host -d -e CONFIGPROXY_AUTH_TOKEN=$TOKEN --name=proxy jupyter/configurable-http-proxy --default-target http://127.0.0.1:9999
docker run --net=host -d -e CONFIGPROXY_AUTH_TOKEN=$TOKEN --name=tmpnb -v /var/run/docker.sock:/docker.sock jupyter/tmpnb python orchestrate.py --container-user=jovyan --command='jupyter notebook --no-browser --port {port} --ip=0.0.0.0 --NotebookApp.base_url={base_path} --NotebookApp.port_retries=0 --NotebookApp.token="" --NotebookApp.disable_check_xsrf=True'

注意：此配置会禁用 Jupyter Notebook 的令牌安全。container-user 选项确保笔记本不会以特权用户运行。若需添加基础安全层，可将 --NotebookApp.token 设置为字符串。

完成后，访问 Docker 主机的 8000 端口即可使用 tmpnb。-v /var/run/docker.sock:/docker.sock 会挂载 Docker 客户端，使编排容器能在主机上生成 Docker 容器（详见这篇文章）。

若使用 docker-machine（现为标准配置），通过 docker-machine ls 获取 Docker 主机 IP；若使用 boot2docker，通过 boot2docker ip 获取 IP。

若启动失败，可运行 docker ps -a 和 docker logs tmpnb 诊断问题。

使用 docker-compose 配置

也可创建 docker-compose.yml 文件：

yaml
httpproxy:
  image: jupyter/configurable-http-proxy
  environment:
    CONFIGPROXY_AUTH_TOKEN: 716238957362948752139417234
  container_name:  tmpnb-proxy
  net: "host"
  command: --default-target http://127.0.0.1:9999
  ports:
    - 8000:8000

tmpnb_orchestrate:
  image: jupyter/tmpnb
  net: "host"
  container_name: tmpnb_orchestrate
  environment:
    CONFIGPROXY_AUTH_TOKEN: 716238957362948752139417234
  volumes:
    - /var/run/docker.sock:/docker.sock
  command: python orchestrate.py --command='jupyter notebook --no-browser --port {port} --ip=0.0.0.0 --NotebookApp.base_url={base_path} --NotebookApp.port_retries=0 --NotebookApp.token="" --NotebookApp.disable_check_xsrf=True'

然后通过 docker-compose up 启动容器，无需构建，直接拉取镜像。

高级配置

如需设置 docker-version 或其他选项，可直接传递给 jupyter/tmpnb：

bash
docker run --net=host -d -e CONFIGPROXY_AUTH_TOKEN=$TOKEN -v /var/run/docker.sock:/docker.sock jupyter/tmpnb python orchestrate.py --cull-timeout=60 --docker-version="1.13" --command="jupyter notebook --NotebookApp.base_url={base_path} --ip=0.0.0.0 --port {port}"

若未指定 docker-version，tmpnb 会自动使用服务器提供的 Docker API 版本。

tmpnb 服务器有两个 API：公共 API（通过 / 代理路由接收 HTTP 请求）和默认仅在本地回环接口可用的管理 API。可通过命令行参数配置两者的接口（--ip、--admin_ip）和端口（--port、--admin_port）。

若需将管理 API 暴露在公共接口，启动 tmpnb 容器时可通过环境变量 ADMIN_AUTH_TOKEN 指定密钥令牌。此后，所有管理 API 请求必须在 HTTP 头中包含：

Authorization: token <管理密钥令牌>

同样，若仅允许特定客户端通过编程方式访问 tmpnb 集群，可通过环境变量 API_AUTH_TOKEN 指定独立密钥令牌。所有公共 API 请求必须以相同方式在 HTTP 头中包含该令牌。注意，设置此令牌后，仅 tmpnb 服务器的 /api/* 资源可用，所有面向用户的路径将被禁用。

使用自定义 Docker 镜像

tmpnb 可运行 --image 选项指定的任何 Docker 容器，只需 --command 选项包含 {base_path} 和 {port} 占位符（含花括号，tmpnb 会替换为分配的路径和端口）：

bash
docker run --net=host -d -e CONFIGPROXY_AUTH_TOKEN=$TOKEN \
           -v /var/run/docker.sock:/docker.sock \
           jupyter/tmpnb python orchestrate.py --image='jupyter/demo' --command="jupyter notebook --NotebookApp.base_url={base_path} --ip=0.0.0.0 --port {port}"

使用 https://github.com/jupyter/docker-stacks 镜像

使用最新 https://github.com/jupyter/docker-stacks 镜像时，可通过 start-notebook.sh 脚本或直接调用 jupyter notebook 命令以 jovyan 用户运行笔记本服务器。将以下命令中的镜像名替换为所需的 docker-stacks 镜像：

bash
docker run -d \
    --net=host \
    -e CONFIGPROXY_AUTH_TOKEN=$TOKEN \
    -v /var/run/docker.sock:/docker.sock \
    jupyter/tmpnb \
    python orchestrate.py --image='jupyter/minimal-notebook' \
        --command='start-notebook.sh \
            "--NotebookApp.base_url={base_path} \
            --ip=0.0.0.0 \
            --port={port} \
            --NotebookApp.trust_xheaders=True"'

选项说明

Usage: orchestrate.py [OPTIONS]

选项:

  --help                           显示帮助信息

tornado/log.py 选项:

  --log-file-max-size              日志文件滚动前的最大大小（默认 100000000）
  --log-file-num-backups           保留的日志文件数量（默认 10）
  --log-file-prefix=PATH           日志文件路径前缀。注意，若运行多个 tornado 进程，每个进程的 log_file_prefix 必须不同（如包含端口号）
  --log-rotate-interval            定时滚动间隔值（默认 1）
  --log-rotate-mode                文件滚动模式（时间或大小）（默认 size）
  --log-rotate-when                指定 TimedRotatingFileHandler 间隔类型，其他选项：('S', 'M', 'H', 'D', 'W0'-'W6')（默认 midnight）
  --log-to-stderr                  将日志输出发送到 stderr（可能带颜色）。默认情况下，若未设置 --log_file_prefix 且未配置其他日志，则使用 stderr
  --logging=debug|info|warning|error|none
                                   设置 Python 日志级别。若为 'none'，tornado 不修改日志配置（默认 info）

orchestrate.py 选项:

  --admin-ip                       管理服务器监听 IP [默认：127.0.0.1]（默认 127.0.0.1）
  --admin-port                     管理服务器监听端口（默认 10000）
  --allow-credentials              设置 Access-Control-Allow-Credentials 头
  --allow-headers                  设置 Access-Control-Allow-Headers 头
  --allow-methods                  设置 Access-Control-Allow-Methods 头
  --allow-origin                   设置 Access-Control-Allow-Origin 头。使用 '*' 允许任何源访问
  --assert-hostname                验证 Docker 守护进程的主机名（默认 False）
  --command                        启动镜像时运行的命令。需提供 {base_path} 占位符，也可提供 {port} 和 {ip} 占位符（默认 jupyter notebook --no-browser --port {port} --ip=0.0.0.0 --NotebookApp.base_url={base_path} --NotebookApp.port_retries=0）
  --container-ip                   容器绑定的主机 IP 地址。若 host_network=True，则为笔记本服务器绑定的主机 IP 地址（默认 127.0.0.1）
  --container-port                 容器内笔记本服务器绑定的端口。若 host_network=True，则为主机上笔记本服务器的起始端口（默认 8888）
  --container-user                 运行容器命令的用户
  --cpu-quota                      每个容器的 CPU 配额。单位为每 100ms 的 CPU-µs，1 CPU/容器对应 --cpu-quota=100000
  --cpu-shares                     每个容器的 CPU 份额限制
  --cull-max                       容器的最大运行时间（秒），无论活动状态。默认：14400（4 小时）。达到此时间的容器将被清理，即使非空闲（默认 14400）
  --cull-period                    清理空闲容器的间隔（秒）（默认 600）
  --cull-timeout                   清理空闲容器的超时时间（秒）（默认 3600）
  --docker-version                 使用的 Docker API 版本（默认 auto）
  --expose-headers                 设置 Access-Control-Expose-Headers 头
  --extra-hosts                    容器的额外主机，可通过逗号分隔的字符串指定多个主机，格式为 hostname:IP（默认 []）
  --host-directories               挂载指定目录作为数据卷，可通过逗号分隔的字符串指定多个目录，路径必须完整（如：/home/steve/data/:r），权限默认为 rw
  --host-network                   将容器附加到主机网络而非默认 Docker 桥接。影响 container_port 和 container_ip 的语义（默认 False）
  --image                          为新用户生成的 Docker 容器。必须已在系统中存在（默认 jupyter/minimal-notebook）
  --ip                             主服务器监听 IP [默认：所有接口]
  --max-age                        设置 Access-Control-Max-Age 头
  --max-dock-workers               最大 Docker 工作进程数（默认 2）
  --mem-limit                      每个容器的内存限制（默认 512m）
  --pool-name                      用于标识属于此实例的容器的名称片段
  --pool-size                      系统上容器的容量。启动时会预启动（默认 10）
  --port                           主服务器监听端口（默认 9999）
  --redirect-uri                   初始笔记本启动时重定向用户的 URI（默认 /tree）
  --static-files                   从初始容器启动中提取的静态文件
  --user-length                    每个容器生成的唯一 /user/:id 路径长度（默认 12）

开发

警告：以下命令中使用的 Makefile 假设容器可被删除。请在隔离机器上操作，并在执行前阅读 Makefile 中的 cleanup 目标。

bash
git clone https://github.com/jupyter/tmpnb.git
cd tmpnb

# 启动代理并运行服务器。默认在所有接口的 8000 端口运行。
# 注意：会停止并删除所有容器
make dev

故障排除

若更改代理端口后收到 500 错误，请确保使用正确的内部端口（默认代理端口 +1，除非另行指定）。