illumidesk/flatiron-notebook

Flatiron Stacks

IllumiDesk为Flatiron School提供的工作区镜像的Dockerfile及相关资源。

前置要求

• Docker

快速开始

1. 安装依赖

bash
make venv

2. 构建镜像

bash
make build-all

3. 运行

独立运行镜像有助于测试：

bash
docker run -p 8888:8888 illumidesk/flatiron-notebook:latest

然后，访问 http://localhost:8888 即可进入Jupyter Notebook服务器。

有关更多 docker run ... 选项，请参考 Docker文档。

4. 测试

bash
make test

镜像目录

构建机制

1. 构建和标记镜像

可单独构建基础镜像或一次性构建所有镜像。使用 TAG 参数添加自定义标签，若未指定，TAG 默认值为 latest。

构建所有镜像：

bash
make build-all

使用自定义标签构建单个镜像：

bash
make build/flatiron-notebook TAG=mytag

2. （可选）将步骤1中的基础镜像用作IllumiDesk栈兼容镜像的基础

dockerfile
FROM jupyter/scipy-notebook:python-3.9.5

RUN ... 执行操作

# 执行操作后确保运行fix-permissions
USER root
RUN fix-permissions "${HOME}" \
 && fix-permissions "${CONDA_DIR}"

USER "${NB_USER}"

3. （可选）推送镜像到DockerHub

若需使用非IllumiDesk的组织，需在DockerHub或其他兼容Docker镜像的 registry 中创建组织账户。docker push ... 命令默认将镜像推送到DockerHub registry。如需推送到其他registry，请参考Docker官方文档。

示例：

bash
docker push illumidesk/flatiron-notebook:python-3.9.5

开发与测试

构建和测试

1. 创建虚拟环境并安装开发依赖：

bash
make venv

2. 使用linter检查Dockerfiles：

bash
make lint-all

3. 构建镜像并运行测试：

bash
make build-all
make test

更新依赖

有两种添加额外依赖的方式：

1. 更新 spec-list.txt 文件中的conda/pip依赖

与Python的 requirements.txt 类似，spec-list.txt 用于锁定依赖树。不同之处在于 spec-list.txt 同时包含conda和pip依赖。

在Docker镜像中更新依赖后，按以下步骤更新 spec-list.txt 文件：

bash
docker run -it --rm -v $(pwd):/tmp illumidesk/flatiron-notebook:<your-tag> /bin/bash

... 安装conda/pip包的步骤 ...

conda list --explicit > /tmp/flatiron-notebook/spec-list.txt

注意：将 <your-tag> 替换为构建镜像时使用的标签。若使用 make 命令，默认值位于 Makefile 中；若使用原生 docker build ... 命令，默认值位于Dockerfile的 FROM 指令中。

2. 更新Dockerfile(s)以添加额外依赖

3. 使用自定义参数（ARGS）构建Docker镜像

使用 docker build 命令的 --build-args 标志覆盖Dockerfile中包含的参数。例如，若要构建/测试使用不同版本Apache Spark（假设版本为 1.2.3）的镜像，可按如下方式构建：

bash
docker build --build-args spark_version=1.2.3 -t illumidesk/flatiron-notebook:mytag flatiron-notebook/.

或

bash
make DARGS="--build-args spark_version=1.2.3" build/flatiron-notebook

发布流程

概述

本仓库配置了两个环境：

• 开发环境：关联 main 分支
• 生产环境：关联 production 分支

开发和生产版本通过DockerHub构建动作构建，分别对应评分器和终端用户Notebook的 illumidesk/flatiron-grader 和 illumidesk/flatiron-notebook。

创建Pull Request

以下步骤适用于 main 和 production 分支。

1. 使用GitHub的 Fork 选项分叉本仓库。
2. 将仓库克隆到本地机器：

bash
$ git clone https://github.com/<github-account>/flatiron-stacks.git

注意：将上述 <github-account> 占位符替换为您的GitHub用户名。

3. 添加远程上游分支：

bash
git remote add upstream https://github.com/illumidesk/flatiron-stacks.git

4. 验证git远程设置是否正确：

bash
git remote -v

上述命令应返回类似以下的输出：

bash
origin  https://github.com/foobar/flatiron-stacks (fetch)
origin  https://github.com/foobar/flatiron-stacks (push)
upstream        https://github.com/illumidesk/flatiron-stacks (fetch)
upstream        https://github.com/illumidesk/flatiron-stacks (push)

5. 通过运行以下命令安装项目所需依赖：

bash
$ make dev
$ source venv/bin/activate

或

bash
$ virtualenv -p python3 venv
$ python3 -m pip install -r dev-requirements.txt
$ source venv/bin/activate

6. 使用以下命令为功能或修复创建新分支：

bash
$ git checkout -b branch-name-here

7. 对要解决的问题进行适当修改。按照 构建和测试 部分的说明构建和测试镜像。请注意，这些只是基本验证，建议使用实际Jupyter Notebook（*.ipynb）文件运行测试。

8. 添加并提交更改的文件：

bash
git add .
git commit -m "my commit message here"

9. 将更改推送到您的分叉仓库：

bash
$ git push origin <branch-name-here>

10. 向上游仓库提交Pull Request。
11. 设置Pull Request的描述。建议使用陈述性术语，例如用 Updates 代替 Updated 或 Updating。
12. 等待Pull Request被维护者审核。
13. 如审核维护者提出建议，对Pull Request进行修改。
14. Pull Request合并后，庆祝成功！ :tada:

合并发布

1. Pull Request获得批准后，将其压缩并合并到 main 或 production 分支。
2. 合并到 main 分支将触发DockerHub构建，标签为 pyspark-dev；合并到 production 分支将创建标签为 pyspark 的构建。
3. 镜像构建完成后，开发和生产集群会自动更新，但需注意以下事项：

• 新版本发布时，运行中的终端用户Notebook不会自动终止。用户需使用Notebook界面中的“Logout”按钮登出并重新登录环境。
• 用户重启环境后会拉取新镜像。
• 新镜像可能是小更新，也可能需要从头下载所有镜像层。因此，第一个启动新Notebook的用户可能需要等待更长时间才能使用Notebook。
• 共享评分器Notebook不会被系统自动更新。如需更新共享评分器Notebook，请在 #flatiron-support Slack频道向IllumiDesk支持团队发送支持请求。如无法访问该频道，可访问 [***] 与客户支持代理聊天获取支持。

参考

这些镜像基于 jupyter/docker-stacks 镜像。参考其文档 获取完整配置选项。

归属

• https://github.com/jupyter/docker-stacks

许可证

MIT