使用 repo2docker 构建 Docker 镜像#

注意

以此方式使用的 Docker 镜像必须包含与 Helm chart 版本匹配的 jupyterhub 包。本文档适用于 Helm chart 4.2.0,它使用 JupyterHub 5.3.0 版本。

如果您找不到满足需求的预构建镜像,可以创建自己的镜像。一种简单的方法是使用 repo2docker 这个包。

repo2docker 可以让您快速将一个 Git 仓库转换为 Docker 镜像,并用作 JupyterHub 实例的基础。当用户访问您的 JupyterHub 时,Git 仓库中的任何内容都会存在于用户的环境中。

repo2docker 会尝试判断应该预安装哪些内容,您可以通过向仓库添加各种配置文件来帮助它。例如,如果您在仓库的根目录中包含一个 requirements.txt 文件,repo2docker 将会使用 pip install 把指定包安装到要构建的 Docker 镜像中。

更多详情请参阅 repo2docker 的文档

下面我们将介绍如何使用 repo2docker 生成 Docker 镜像,以及如何配置 JupyterHub 以此镜像为基础进行构建。

  1. 下载并启动 Docker。

    您可以通过下载并安装 Docker 来完成此操作。启动 Docker 后,它会以一个微小的后台应用程序形式出现。

  2. 使用 pip 安装 repo2docker

    pip install jupyter-repo2docker
    

    如果该命令因权限不足而失败,请尝试加上 user 命令选项

    pip install --user jupyter-repo2docker
    
  3. 创建(或找到)一个您想使用的 Git 仓库。

    这个仓库应包含您希望用户能够使用的所有材料。您可能需要包含一个 pip requirements.txt 文件,用于列出要安装的软件包,每行列出一个,就像使用 pip install 时一样。请明确指定版本,以确保镜像是完全可复现的。下面是一个 requirements.txt 的示例

    jupyterhub==0.9.4
    numpy==1.14.3
    scipy==1.1.0
    matplotlib==2.2.2
    
  4. 获取 Docker 仓库的凭据。

    您为 JupyterHub 构建的镜像必须通过发布到某个容器注册中心来提供。例如,您可以使用 quay.ioDocker Hub

    在下一步中,您需要一个镜像引用,以便您和他人可以找到您的镜像。

    Docker Hub 上的镜像引用

    <dockerhub-username>/<image-name>:<image-tag>
    

    quay.io 上的镜像引用

    quay.io/<quay-username>/<image-name>:<image-tag>
    
    • 您的镜像名称可以是任何容易记住的名字。

    • 我们建议使用 Git commit SHA 的前 7 个字符,因为这可以提高可复现性。您可以通过多种方式获取,其中一种如下

      git ls-remote <your-git-repository> | grep HEAD | awk '{ print $1 }' | cut -c -7
      
  5. 使用 repo2docker 构建 Docker 镜像。

    jupyter-repo2docker \
        --no-run \
        --user-name=jovyan \
        --image=<your-image-reference> \
        <a-git-repository-url>
    

    这会告诉 repo2docker 获取 Git 仓库的默认分支,并使用启发式方法为其构建一个 Docker 镜像。

  6. 将新构建的 Docker 镜像推送到您的仓库。

    docker push <your-image-reference>
    
  7. 编辑 JupyterHub 配置,使其基于此镜像构建。 编辑 config.yaml 文件,在其中包含以下几行

    singleuser:
      image:
        name: <your-image-reference>
        tag: "<tag>"
    

    如果标签是 SHA 的前几个字符,并且它们恰好都是数字,您*必须*像上面那样在标签周围使用引号,以确保 YAML 被正确解析。

  8. 告知 Helm 更新 JupyterHub 以使用此配置。

    使用标准方法应用配置更改

  9. 如果您已经登录,请重启您的服务器。

    如果您已经有一个正在运行的 JupyterHub 服务器,您需要从 JupyterHub 控制面板重启它。在 JupyterLab 中,查看名为“Hub”的菜单。新用户则无需此操作。

    注意

    如果您启用了持久化存储,您的 GitHub 仓库内容可能不会显示。如果您希望显示 Git 仓库内容,请禁用持久化存储。

  10. 享受您的新计算环境吧!

    您现在应该拥有一个基于我们创建的 Docker 镜像构建的实时计算环境了。