sgibson91/binderhub-setup

BinderHub Azure自动部署镜像

镜像概述和主要用途

BinderHub是一种基于云的多服务器技术，用于托管从代码仓库构建的可重现计算环境和交互式Jupyter Notebook。本Docker镜像包含一系列脚本，可在Microsoft Azure上自动部署BinderHub，并连接Docker Hub账户/组织或Azure容器注册表（ACR），帮助用户搭建自托管的Binder服务。

该镜像基于Google Cloud部署脚本集https://github.com/nicain/binder-deploy%E5%BC%80%E5%8F%91%EF%BC%8C%E9%80%82%E7%94%A8%E4%BA%8E%E9%9C%80%E8%A6%81%E5%9C%A8Azure%E5%B9%B3%E5%8F%B0%E4%B8%8A%E5%BF%AB%E9%80%9F%E9%83%A8%E7%BD%B2BinderHub%E7%9A%84%E4%B8%AA%E4%BA%BA%E6%88%96%E7%BB%84%E7%BB%87%E3%80%82%E4%BD%BF%E7%94%A8%E5%89%8D%E9%9C%80%E6%8B%A5%E6%9C%89Microsoft Azure账户和订阅（可通过Azure免费试用获取）。

核心功能和特性

• 自动化部署：通过脚本自动完成Kubernetes集群创建、Helm Chart安装和配置文件生成
• 多容器注册表支持：兼容Docker Hub（公开镜像）和Azure容器注册表（ACR，私有镜像）
• HTTPS配置：集成cert-manager和Let's Encrypt，支持自定义域名的HTTPS证书配置
• 完整生命周期管理：提供部署（deploy.sh）、升级（upgrade.sh）、监控（logs.sh/info.sh）和销毁（teardown.sh）全流程脚本
• "一键部署"支持：通过"Deploy to Azure"按钮实现简化部署流程
• 日志管理：支持本地日志存储和Azure Blob存储日志备份

使用场景和适用范围

• 学术机构或研究团队需要为成员提供可重现的交互式计算环境
• 教育机构搭建基于Jupyter Notebook的教学平台
• 开发团队共享可交互的代码示例和技术文档
• 需要私有镜像仓库支持的企业级Binder服务部署
• Azure用户希望简化BinderHub部署流程，减少手动配置工作

详细使用方法和配置说明

前提条件

• Microsoft Azure账户和有效订阅
• （可选）Docker Hub账户或组织
• （可选）自定义域名（如需启用HTTPS）

本地运行容器

克隆仓库并准备配置文件

bash
git clone https://github.com/alan-turing-institute/binderhub-deploy.git
cd binderhub-deploy
cp template-config.json config.json

配置文件格式

config.json是核心配置文件，包含部署所需的所有参数，格式如下：

json
{
  "container_registry": "",        // 容器注册表类型："dockerhub"或"azurecr"
  "enable_https": "false",         // 是否启用HTTPS："true"或"false"
  "acr": {
    "registry_name": null,         // ACR名称（仅azurecr时必填，需唯一且字母数字组成）
    "sku": "Basic"                 // ACR SKU层级（Basic/Standard/Premium）
  },
  "azure": {
    "subscription": "",            // Azure订阅名称或ID
    "res_grp_name": "",            // Azure资源组名称
    "location": "",                // Azure数据中心区域（如"westeurope"）
    "node_count": 1,               // 节点数量（建议3个以保证稳定性）
    "vm_size": "Standard_D2s_v3",  // 虚拟机类型（如"Standard_D2s_v3"）
    "sp_app_id": null,             // Azure服务主体ID（可选）
    "sp_app_key": null,            // Azure服务主体密码（可选）
    "sp_tenant_id": null,          // Azure租户ID（可选）
    "log_to_blob_storage": false   // 是否将日志存储到Blob（非容器运行时）
  },
  "binderhub": {
    "name": "",                    // BinderHub名称
    "version": "",                 // Helm Chart版本（格式：0.2.0-<commit-hash>）
    "image_prefix": ""             // Docker镜像前缀（如"binder-prod"）
  },
  "docker": {
    "username": null,              // Docker用户名（可在运行时提供）
    "password": null,              // Docker密码（可在运行时提供）
    "org": null                    // Docker Hub组织（可选）
  },
  "https": {
    "certmanager_version": null,   // cert-manager版本
    "contact_email": null,         // Let's Encrypt联系邮箱
    "domain_name": null,           // 域名
    "nginx_version": null          // nginx-ingress版本
  }
}

注意：免费试用订阅有4核限制，需根据vm_size（单节点核心数）和node_count（节点数）合理配置。

核心脚本使用

setup.sh - 环境准备

检查并安装必要的命令行工具：Azure CLI、Kubernetes（kubectl）、Helm。

bash
cd src
chmod 700 setup.sh
./setup.sh

deploy.sh - 部署BinderHub

读取config.json配置，部署Kubernetes集群，创建配置文件并安装BinderHub。

bash
chmod 700 deploy.sh
./deploy.sh

如使用Docker Hub且未在配置文件中提供凭据，脚本会提示输入Docker用户名和密码。

logs.sh - 查看日志

打印JupyterHub日志以辅助调试：

bash
chmod 700 logs.sh
./logs.sh

info.sh - 获取部署信息

显示Kubernetes pod状态和BinderHub/JupyterHub IP地址：

bash
chmod 700 info.sh
./info.sh

upgrade.sh - 升级部署

升级Helm Chart配置并重启相关pod：

bash
chmod 700 upgrade.sh
./upgrade.sh

teardown.sh - 销毁部署

删除Helm发布、Kubernetes命名空间和Azure资源组：

bash
chmod 700 teardown.sh
./teardown.sh

"Deploy to Azure"按钮部署

通过Azure门户一键部署：

服务主体创建

部署前需创建Azure服务主体（Service Principal）：

1. 在Azure门户打开Cloud Shell（Bash模式）
2. 设置订阅：az account set --subscription <订阅ID>
3. 创建服务主体：

   bash
   # 用于Docker Hub
   az ad sp create-for-rbac --name binderhub-sp --role Contributor --scope /subscriptions/<订阅ID>
   
   # 用于ACR（需Owner权限）
   az ad sp create-for-rbac --name binderhub-sp --role Owner --scope /subscriptions/<订阅ID>
   

4. 记录输出的appId（服务主体ID）、password（服务主体密钥）和tenant（租户ID），用于部署表单填写

监控部署进度

1. 登录Azure门户，进入部署所在的资源组
2. 选择容器实例，进入"设置->容器"
3. 查看容器日志（需定期刷新）了解部署进度

获取部署输出

部署完成后，日志和配置文件会存储在Azure存储账户中，可通过Azure CLI下载：

bash
# 下载所有文件
az storage blob download-batch --account-name <存储账户名> --source <容器名> --pattern "*" --destination <本地目录>

# 下载特定日志文件
az storage blob download-batch --account-name <存储账户名> --source <容器名> --pattern "*.log" --destination <本地目录>

HTTPS配置（可选）

如需为自定义域名启用HTTPS，需完成以下手动步骤：

1. 域名委托：将域名的NS记录更新为脚本生成的DNS区域名称服务器（保存在name-servers.log）
2. 设置A记录：运行set-a-records.sh将负载均衡器IP绑定到域名的A记录：

   bash
   chmod 700 set-a-records.sh
   ./set-a-records.sh
   

3. 切换Let's Encrypt环境：验证 staging 证书后，按文档切换到生产环境以获取可信证书

自定义部署

可通过修改模板文件（templates目录）自定义BinderHub配置，包括资源限制、认证方式、UI样式等。修改后需重新运行deploy.sh应用更改。

开发者指南

构建测试镜像

bash
docker build -t binderhub-setup:test .

版本标记

遵循语义化版本规范，使用Git标签标记发布版本：

bash
git tag -a v1.0.0 -m "Initial stable release"
git push origin v1.0.0

注意事项

• 免费试用订阅有资源限制，建议生产环境使用标准订阅
• config.json包含敏感信息，已被git忽略，请勿提交到版本库
• 销毁部署后，建议在Azure门户确认资源已完全删除
• ACR部署需服务主体拥有Owner权限，而Docker Hub仅需Contributor权限