ucsdets/cogs189-notebook

为DataHub/DSMLP构建自定义镜像的指南

本指南适用于高级DSMLP用户（包括学生和教师），他们希望通过自定义Docker容器在工作环境中添加或修改应用。

对于支持CUDA的镜像，请切换到cuda分支获取更多信息。

简介

Docker 镜像是打包的应用程序、依赖项和底层操作系统的快照。用户可以在任何运行Docker平台的机器上使用相同的Docker镜像，并获得相同的软件功能和行为。Docker Hub是一个公共容器注册表，您可以在其中下载（"拉取"）和上传（"推送"）Docker镜像。就像GitHub托管git仓库一样，Docker Hub托管和分发Docker镜像。在本指南中，我们将通过修改Dockerfile、在所需平台上构建镜像并将其发布到Docker Hub来构建自定义Docker镜像。

构建和维护Docker镜像遵循三个基本步骤：构建、共享和部署/测试。您可能需要多次执行这些步骤，直到达到预期效果。您可以在https://docs.docker.com/get-started/%E6%89%BE%E5%88%B0%E6%BC%94%E7%A4%BA%E4%B8%80%E8%88%AC%E6%83%85%E5%86%B5%E7%9A%84%E5%AE%98%E6%96%B9%E6%95%99%E7%A8%8B%EF%BC%8C%E4%BD%86%E6%9C%AC%E6%96%87%E6%A1%A3%E6%98%AF%E4%B8%93%E9%97%A8%E4%B8%BADSMLP%E7%94%A8%E6%88%B7%E9%87%8F%E8%BA%AB%E5%AE%9A%E5%88%B6%E7%9A%84%E3%80%82

2021年6月新变化

Docker Hub修改了其免费计划，https://www.docker.com/blog/changes-to-docker-hub-autobuilds/%E8%AE%B8%E5%A4%9A%E7%94%A8%E6%88%B7%E4%BE%9D%E8%B5%96%E7%9A%84Autobuilds%E5%8A%9F%E8%83%BD%EF%BC%8C%E8%AF%A5%E5%8A%9F%E8%83%BD%E6%9B%BE%E5%85%81%E8%AE%B8%E7%94%A8%E6%88%B7%E5%9C%A8Docker Hub的基础设施上免费构建镜像。本指南的内容将反映这一变化，不再推荐将Docker Hub作为构建平台。

步骤0：前提条件

• 一个新的公共GitHub git仓库，使用本指南作为模板。点击右上角的"Use this template"。您也可以使用现有公共仓库，只需在仓库根目录添加Dockerfile。公共可见性是为了使用GitHub提供的免费计划，这在后续步骤中会用到。

• 一个Docker Hub账户。在https://hub.docker.com/注册。您需要此账户来发布新镜像和配置自动构建。

• 一个新的公共Docker Hub仓库。其名称不必与GitHub仓库相同。

• 在Docker Hub账户上创建访问令牌。按照此[文档]操作。将其命名为"For Github Actions"并将生成的令牌保存在本地。

步骤1：自定义Dockerfile

步骤1.1 基础镜像

• 通过取消注释设置BASE_CONTAINER参数的相应行来选择基础容器

  • https://support.ucsd.edu/its?id=kb_article_view&sysparm_article=KB0032173&sys_kb_id=***dbe69810a4bc41db***
  • datahub-base-notebook镜像包含Jupyter和Python、R的常用数据科学工具。源自https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html#jupyter-datascience-notebook%E3%80%82
  • datascience-notebook镜像使用pip安装了更多软件包。
  • scipy-ml镜像包含更广泛的软件包，包括tensorflow、pytorch，支持CUDA 11，通常用于GPU加速工作流。

• 注意：尽管scipy-ml功能更多，但在其基础上构建镜像会花费更长时间。为了节省镜像大小和减少构建时间，最好在base-notebook上应用最小的必要工具集。

步骤1.2 系统包

• 使用USER root获取root权限以安装系统包。此行已为您写好。

• 使用apt-get安装系统级包

  • 第19行的示例安装了名为htop的系统工具。
  • 指定更多包作为额外参数：apt-get -y install htop ping

步骤1.3 Python库

• 注意：建议尽可能使用pip而不是conda。pip在解决包冲突方面更宽容，通常速度更快。

• 安装conda包

  • 使用RUN conda install --yes <package1> <package2>一次性安装所有所需的conda包
  • （可选）使用RUN conda clean -tipy减少镜像大小

• 安装pip包

  • 仅在conda之后使用pip。
  • 使用pip install --no-cache-dir <package>
  • 或者，您可以在项目根目录提供requirements.txt文件，并使用pip install --no-cache-dir -r requirements.txt引用它。每个包单独一行。

• 保留Dockerfile的其余部分不变

步骤2：构建镜像

在本步骤中，您将使用创建的Dockerfile构建镜像。这里有两个选项：

1. 安装Docker客户端并在本地构建镜像，然后推送到（上传）Docker Hub。这需要您在本地Windows PC/Mac上安装https://www.docker.com/products/docker-desktop%EF%BC%8C%E6%88%96%E5%9C%A8Linux%E4%B8%8A%E5%AE%89%E8%A3%85https://docs.docker.com/engine/install/%E3%80%82%E6%82%A8%E4%B9%9F%E5%8F%AF%E4%BB%A5%E4%BD%BF%E7%94%A8%E5%AE%89%E8%A3%85%E4%BA%86Docker%E7%9A%84%E8%BF%9C%E7%A8%8BLinux%E6%9C%8D%E5%8A%A1%E5%99%A8%E6%9D%A5%E6%9E%84%E5%BB%BA%E5%92%8C%E6%B5%8B%E8%AF%95Docker%E9%95%9C%E5%83%8F%E3%80%82%E5%91%BD%E4%BB%A4%E7%9B%B8%E5%90%8C%EF%BC%8C%E4%BD%86%E5%A6%82%E6%9E%9C%E6%82%A8%E6%9C%AC%E5%9C%B0%E6%B2%A1%E6%9C%89Docker%EF%BC%8C%E5%88%99%E6%97%A0%E6%B3%95%E5%9C%A8%E6%9C%AC%E5%9C%B0%E5%BC%80%E5%8F%91%EF%BC%8C%E5%8F%AA%E8%83%BD%E5%9C%A8DSMLP%E4%B8%8A%E5%BC%80%E5%8F%91%E3%80%82%E5%AF%B9%E4%BA%8EWindows%E5%BC%80%E5%8F%91%EF%BC%8C%E5%BC%BA%E7%83%88%E5%BB%BA%E8%AE%AE%E5%AE%89%E8%A3%85WSL 2引擎以获得更好的体验。

2. 利用免费的https://docs.docker.com/docker-hub/builds/#configure-automated-build-settings%E6%9C%8D%E5%8A%A1%EF%BC%8CDocker Hub将为您构建和分发镜像。如果您有信心，可以直接选择此选项，但如果出现构建问题，调试和定位问题会相当困难。 已移除，因为不再免费

3. 在项目中设置https://github.com/features/actions%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E3%80%82%E6%8F%90%E4%BE%9B%E4%BA%86%E4%B8%80%E4%B8%AA%E6%A8%A1%E6%9D%BF%EF%BC%8C%E5%8F%AA%E9%9C%80%E6%9C%80%E5%B0%91%E7%9A%84%E4%BF%AE%E6%94%B9%E3%80%82

建议同时使用这两种方法，以便于调试和缩短成功构建的周转时间。选项2更容易，但为了理解基础知识，请先完成选项1。在本地安装Docker有时会很麻烦，但是您可以利用https://education.github.com/pack%E6%8F%90%E4%BE%9B%E7%9A%84100***DigitalOcean%E4%BF%A1%E7%94%A8%E9%A2%9D%E5%BA%A6%EF%BC%8C%E5%9C%A8%E9%82%A3%E9%87%8C%E5%90%AF%E5%8A%A8%E4%B8%80%E4%B8%AADocker Droplet。或者使用任何免费的远程Linux服务器。请查看附录中的资源。

选项1：使用Docker Desktop/Docker Engine

安装Docker后，启动终端并导航到包含Dockerfile的git目录。

确保仔细检查GitHub/DockerHub账户名称以及GitHub仓库和Docker Hub仓库的名称。当您从其他地方拉取镜像时，完整镜像名称将是<dockerhub-username>/<dockerhub-repo-name>，后面可选择添加:<tag>。如果未提供标签，将默认使用:latest。我们将此全名称为<image-fullname>，用于后续命令。

步骤2.1.1 构建

输入"docker build -t <image-fullname> ."并按<Enter>，注意命令末尾的"点"，表示当前目录。Docker将在当前目录的上下文中构建镜像。生成的镜像将被标记为<image-fullname>。监控构建过程是否有错误。

步骤2.1.2 调试

如果构建失败，记录Docker最后运行的命令并从那里开始调试。编辑Dockerfile后再次运行构建命令。有时，最好启动步骤之后的中间docker镜像，并从那里启动镜像尝试一些命令。为此，使用步骤2.1.3中的测试运行命令。

这将帮助您找到中间镜像的名称。如果Step 4失败，查看输出并找到Step 3的镜像，在以下示例输出中，我们将使用镜像51a4d2ec5e16进行调试。

Step 3/14 : USER root           # 步骤编号和命令
 ---> Running in 4e32937f1e93   # 临时容器
 ---> 51a4d2ec5e16              # 结果镜像（用于调试）

这里的一些常见错误/问题包括：

1. 未向安装命令提供默认的-y选项，导致超时。

2. 如果错误消息显示在某个文件中找到/r/n，请将行尾序列从CRLF更改为LF。您可以在编辑器中执行此操作，或使用dos2unix工具。这通常发生在Windows机器上。

步骤2.1.3 测试运行

• 镜像成功构建后，使用docker run --rm -it <image-fullname> /bin/bash进入镜像。-it表示交互模式，--rm告诉docker在退出后删除容器。检查是否具有所需的所有功能。使用exit退出容器。如果有问题，返回构建步骤重新开始。

步骤2.1.4 推送

• 在Docker客户端上登录Docker Hub。可以使用GUI或命令docker login <username>完成。

• 推送镜像docker push <image-fullname>，标签默认为latest。如果要推送不同的标签，在全名末尾添加:<tag>。

• 如果您使用的是按使用付费的远程Linux VM（如DigitalOcean），不要忘记删除实例以节省成本！

选项2：在Docker Hub上设置自动构建

选项2：使用Github Actions

完成前一个选项后，您应该熟悉构建、测试和推送Docker镜像的整个工作流程。现在我们可以使用Github Actions自动为我们完成这些事情，免费！

1. 创建新文件.github/workflows/docker.yml及其包含的目录。注意这里的.github是一个隐藏目录，在Windows上如果未启用显示隐藏文件的设置，可能会图形化隐藏。

2. 我们将使用此仓库中的相同文件作为您的模板。这是一个YAML配置文件，使用Github Workflows的语法。在jobs.docker.steps.[1]中，填写前面的<image-fullname>和您的Docker Hub用户名。

3. 其余内容保持不变。您会发现它包含了选项1中的所有必要步骤。如果有信心，可以添加更多步骤来增强工作流。

4. 重要：进入您的Github仓库设置，在"Secrets"下，创建"New Repository Secret"。使用名称"DOCKERHUB_PASSWORD"并填写前提条件中保存的令牌。运行此操作时，密钥将被传入并在工作流日志（公开）中隐藏。

5. 提交并推送更改到GitHub。在"Actions"选项卡中，将有一个新的工作流，您可以在其中检查进度和输出。

6. 此工作流的触发器定义得很窄。只有当main或master分支中的["requirements.txt", "Dockerfile", ".github/workflows/main.yml"]中的任何一个被更改时，它才会运行。可以随意修改此行为。

有关更多信息，请查看Github Actions语法和相关文档，https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions%E3%80%82

步骤3：在DSMLP上启动Pod

• SSH到dsmlp-login.ucsd.edu

• 运行launch-scipy-ml.sh -i <image-fullname> -P Always。-P Always标志将强制docker主机同步，因为它会拉取镜像清单的最新版本。注意：docker镜像名称遵循<user>/<image>:<tag>格式。如果未向启动脚本提供:<tag>部分，将假定为:latest。在构建步骤中使用v1或test等标签，以控制同一docker镜像的不同版本。

• 等待节点下载镜像。下载时间取决于镜像大小。

• 如果超时/启动失败，检查kubectl logs <pod-name>或联系ETS服务台寻求帮助。

提示

• 如果您在一天内重复使用pod或将自定义镜像在少数人之间共享，请使用相同的节点以减少启动时间（无需下载）。可以通过在启动命令末尾添加-n <node-number>来实现。

• 要禁用进入时启动jupyter notebook，通过添加CMD ["/bin/bash"]作为最后一层（Dockerfile的最后一行）来覆盖默认可执行文件。您始终可以再次启动notebook并在dsmlp-login上手动端口转发：kubectl port-forward pods/<POD_NAME> <DSMLP_PORT>:8888

资源/进一步阅读

• https://support.ucsd.edu/its?id=kb_category&kb_category=7defd803db49fb08bd30f6e9af961979&kb_id=e343172edb3c1f40bd30f6e9af961996
• https://docs.docker.com/develop/develop-images/dockerfile_best-practices/
• https://www.docker.com/sites/default/files/d8/2019-09/docker-cheat-sheet.pdf
• https://docs.google.com/document/d/1LPfqHvk2Itm_ckafrxRVxXQdr5BSozjsv_TURQDj9x8/edit

附录

• https://marketplace.digitalocean.com/apps/docker%EF%BC%8C%E8%BF%99%E5%B0%86%E4%B8%BA%E6%82%A8%E6%8F%90%E4%BE%9B%E4%B8%80%E4%B8%AA%E5%B7%B2%E5%AE%89%E8%A3%85Docker%E7%9A%84Linux VM，随时可用。从至少8GB内存的配置开始，如果处理大型镜像，可以增加配置。
• https://education.github.com/pack