安装并运行本地课程开发¶

本页介绍了在 Docker 中本地安装和运行课程的过程。您可以按照以下说明或使用浏览器内工具在本地开发课程内容。

为什么要在本地运行ZJUI-Learn？¶

ZJUI-Learn 提供使用浏览器界面创建和更新问题的能力。虽然此界面适合解决简单的问题，但对于复杂的情况并不理想，例如：

使用代码自动评分的问题
使用工作空间的问题
涉及大量图像、文档和其他文件的问题
在生成和/或评分过程中使用自定义 Python 库的问题
自定义元素或元素扩展

将课程存储库与本地安装结合使用可以简化更新课程内容的过程。此工作流程允许教师测试问题代码或评估配置的更改，而不会影响学生的体验。它还支持使用 Git 工作流程和拉取请求在课程中与多名员工进行协作和协调。

安装说明¶

无论您使用哪种操作系统，都需要安装适当版本的Docker Desktop。对于 Windows 用户，您还需要安装 WSL 2 并启用其与 Docker Desktop 的集成。有关更多详细信息，请参阅下面的针对 Windows 用户的其他说明部分。

克隆您的课程存储库¶

如果您仅运行 ZJUI-Learn 示例课程，则可以跳过本节。

当您请求课程时，您通常会收到课程内容的 GitHub 存储库 URL。您可以使用 Git 将本课程内容克隆（制作本地副本）到您自己的计算机中。记下您要将课程克隆到的目录。如果您正在使用多个课程，则需要将每个课程存储在单独的目录中。对于 Windows 用户，建议将课程内容存储在 WSL 2 实例中以获得更好的性能。

运行说明¶

以下指令必须在终端窗口中执行。对于 MacOS 和 Linux，您可以使用默认终端应用程序。对于 Windows，使用连接到 WSL 2 实例的终端。

要仅使用示例课程运行 ZJUI-Learn，请打开终端窗口并键入命令：

docker run -it --rm -p 3000:3000 prairielearn/prairielearn

要使用您自己的课程，请使用 -v 标志将 Docker /course 目录与您自己的课程目录绑定。例如，如果您的课程存储在 $HOME/pl-tam212 中，则命令为：

docker run -it --rm -p 3000:3000 -v $HOME/pl-tam212:/course prairielearn/prairielearn

确保将课程路径替换为您自己的课程目录。要使用多个课程，请添加额外的 -v 标志（例如 -v /path/to/course1:/course -v /path/to/course2:/course2）。您可以通过此方法使用最多九个课程，使用安装点：/course、/course2、/course3、...、/course9。

运行上述命令后，您应该看到一条消息：

ZJUI-Learn server ready, press Control-C to quit

该消息显示后，打开网络浏览器并连接到 http://localhost:3000/pl.

完成 ZJUI-Learn 后，在运行服务器的终端上键入 Control-C 以停止它。

支持外部评分者和工作区¶

要在本地运行 ZJUI-Learn 并支持外部评分器和工作区，需要执行一些额外的步骤。

首先，创建一个空目录用于在容器之间共享作业数据。该目录可以位于任何地方，但需要首先创建并在 Docker 启动命令中引用。该目录只需创建一次。如果您运行的是 Windows，则应在 WSL 2 实例内创建该目录。您可以使用如下命令创建此目录：

mkdir "$HOME/pl_ag_jobs"

现在，我们可以运行带有附加选项的 ZJUI-Learn，以允许外部分级或工作区功能。例如，如果您的课程目录位于 $HOME/pl-tam212，上面创建的作业目录位于 $HOME/pl_ag_jobs，则新命令如下：

docker run -it --rm -p 3000:3000 \
  -v "$HOME/pl-tam212:/course" `# Replace the path with your course directory` \
  -v "$HOME/pl_ag_jobs:/jobs" `# Map the jobs directory into /jobs` \
  -e HOST_JOBS_DIR="$HOME/pl_ag_jobs" \
  -v /var/run/docker.sock:/var/run/docker.sock `# Mount Docker into container so it can spawn others` \
  --add-host=host.docker.internal:172.17.0.1 `# Ensure network connectivity` \
  prairielearn/prairielearn

???问题“为什么这是必要的？”

In production, ZJUI-Learn runs external grading jobs and workspaces on a distributed system that can efficiently run many jobs in parallel. When developing questions locally, you won't have access to this infrastructure, but ZJUI-Learn allows you to still run external grading jobs and workspaces locally. To do this, it needs extra Docker command line arguments to provide two key capabilities:

- ZJUI-Learn needs a way of starting up Docker containers on the host machine from within another Docker container. This is achieved by mounting the Docker socket from the host into the Docker container running ZJUI-Learn; this allows it to run "sibling" containers.
- ZJUI-Learn needs to get job files from inside the Docker container running ZJUI-Learn to the host machine so that Docker can mount them to either `/grade` in the grading container or the home directory in the workspace container. This is achieved by mounting a directory on the host machine to `/jobs` in the ZJUI-Learn container, and setting an environment variable `HOST_JOBS_DIR` containing the absolute path of that directory on the host machine.

发展¶

如果您想为 ZJUI-Learn 贡献改进或功能，您将需要以不同的方式启动 ZJUI-Learn。有关更多详细信息，请参阅本地安装文档。

对 --add-host 选项和网络超时进行故障排除¶

如果您是 Docker 高级用户，或者您组织的网络策略需要，那么您之前可能已经调整过 Docker 使用的地址池。如果这与 Docker 默认值冲突，您在尝试本地启动工作区时可能会收到网络超时错误。在这种情况下，您可能需要调整 --add-host= 选项的 IP 地址。您可以在此处找到更多技术详细信息：PL 问题 #9805、moby/moby PR 29376、docker/docs 问题 8663。

如果您使用的是 macOS，那么您可以完全删除 --add-host 选项，不会出现任何问题。

升级您的 ZJUI-Learn Docker 映像¶

要随时获取最新版本的 ZJUI-Learn，请确保 ZJUI-Learn 未运行（如果需要，请按 Ctrl-C），然后运行：

docker pull prairielearn/prairielearn

之后，使用与上述相同的命令运行 ZJUI-Learn。

运行特定版本的 ZJUI-Learn¶

上面的命令将始终运行 ZJUI-Learn 的最新版本，这可能是未发布的开发版本。如果您想运行当前部署的版本，请使用适合您正在使用的服务器的标签：

对于在 https://us.prairielearn.com/ 下运行的课程，请使用标签 us-prod-live；
对于本地安装了 ZJUI-Learn 的机构，请咨询当地的 IT 部门。

docker run -it --rm -p 3000:3000 --pull=always [other args] prairielearn/prairielearn:us-prod-live

Tip

上面的命令使用了 --pull=always 选项，每次重新启动 Docker 命令时都会更新本地版本的镜像。如果您在本地保留长时间运行的容器，请确保在 ZJUI-Learn GitHub 讨论页面中宣布生产服务器中的更新时重新启动容器。

旧版本可使用附加标签。可用版本列表可在 Docker Hub 构建页面上查看。

针对 Windows 用户的附加说明¶

由于极端的性能问题、与作业文件夹中的文件权限相关的限制以及与文件格式相关的问题，我们目前不支持没有 WSL 2 的 Windows 环境。虽然有多种方法可以在此环境中运行 ZJUI-Learn，但它可能无法提供学生在生产环境中看到的相同体验，因此不鼓励这样做，也没有记录在案。

如果您使用的是 Windows，请使用 WSL 2 运行 ZJUI-Learn。 WSL 2 提供了与 Windows 一起运行的 Linux 环境，并更好地利用现代 CPU 虚拟化功能。本页中的所有示例均假设，如果使用 Windows，则执行命令且文件存储在 WSL 2 环境中。

以下是安装 WSL 2 并启用其与 Docker 集成的说明：

安装 WSL 2。有关当前说明，请遵循 Microsoft 文档。
启用 Docker Desktop WSL 2 后端。有关当前说明，请遵循 Docker 文档。

在 Windows 上打开 WSL 2 shell¶

要运行 WSL 2 shell，请打开 Windows“开始”菜单，搜索“WSL”，然后选择您安装的 WSL 2 实例。或者，安装 Windows Terminal 应用程序并从下拉菜单中选择您的 WSL 2 实例。

请注意，不支持 PowerShell、命令提示符、Git Bash、Cygwin、MinGW 和其他类似环境，并且可能无法正常工作。您可以通过在终端中输入 echo $WSL_DISTRO_NAME 来检查您是否使用 WSL shell。如果您看到在上一步中安装的 Linux 发行版的名称，则您正在使用 WSL。如果您什么也没看到，或者看到 $WSL_DISTRO_NAME，则表明您没有使用 WSL。

将课程内容存储在 WSL 2 中¶

虽然有多种方法可以将课程内容存储在 Windows 文件系统本身中（例如，在文档或桌面文件夹中，或 C:\ 驱动器内的其他位置）并将这些路径转换为 WSL 安装路径（例如，通过 /mnt/c/... 路径），但由于性能问题，不建议使用这些方法。

如果您使用的是 Windows，请将课程内容存储在 WSL 2 实例中。当本地运行 ZJUI-Learn 时，此选项通常可提供最佳性能。您可以在 WSL shell 中使用 git 命令克隆存储库。请注意，在这种情况下，您需要使用 WSL 工具和编辑器更新文件，或者使用 Linux 文件系统访问文件。此处列出了执行此操作的说明。在这种情况下，请跟踪您的课程在 WSL 中使用的路径（例如 $HOME/pl-tam212）。