texastribune/base

tt-docker-base

自2022年11月30日起，本仓库不再作为Texas Tribune网站和CMS的基础镜像。目前，它仍用于salaries应用。

镜像概述和主要用途

tt-docker-base是Texas Tribune开发的基础Docker镜像，主要为应用提供统一的运行环境和依赖管理机制。尽管已不再作为网站和CMS的基础镜像，但其仍在salaries应用中发挥作用，支持Python和Node依赖的添加、更新与管理，并提供完整的测试和部署流程，确保依赖更新不会引入意外行为。

核心功能和特性

• 依赖管理：支持Python（通过Poetry）和Node（通过npm）依赖的添加、更新和版本固定
• 安全测试：提供Dependabot PR本地测试流程，验证依赖更新的安全性和兼容性
• 镜像构建：可构建开发（dev）和基础（base）两种环境镜像，满足不同场景需求
• 版本控制：通过make bump命令实现版本号管理和标签推送，确保部署一致性

使用场景和适用范围

• salaries应用的日常开发和维护
• 处理Dependabot生成的依赖安全更新PR
• 需要统一Python和Node运行环境的开发场景
• 对依赖版本变更进行本地验证和测试

使用方法和配置说明

测试Dependabot PRs

GitHub的Dependabot会定期创建PR以更新包版本，修复已知安全问题。为确保这些更新不会对Texas Tribune网站造成意外影响，建议在合并和部署前进行本地测试。

请参考Dependabot测试指南获取测试和部署的详细步骤。

更新依赖

以下说明提供了在本仓库中更新、添加或删除Python和Node依赖的通用指南。

准备工作

sh
# 拉取最新代码
git pull origin master

# 创建功能分支
git checkout -b <新分支名称>

添加或更新依赖

Python依赖

若要添加或更新Python依赖：

1. 在容器内运行shell

   sh
   make base-shell
   

2. 添加或更新Python依赖

   sh
   # 在步骤1进入的容器shell中执行：
   
   # 添加或升级生产环境Python依赖
   poetry add <包名>
   
   # 添加或升级开发环境依赖
   poetry add --dev <包名>
   
   # 固定依赖到特定版本
   poetry add <包名>@1.0.0
   

3. 返回本地机器shell

   sh
   exit
   

4. 继续本地构建和测试。

虽然推荐使用poetry CLI，但也可手动编辑pyproject.toml，然后在容器内运行poetry lock实现相同效果。

更多命令和使用细节请参见poetry文档。

Node依赖

若要添加或更新Node依赖：

1. 在容器内运行shell

   sh
   make dev-shell
   

2. 添加或更新Node依赖

   sh
   # 在步骤1进入的容器shell中执行：
   
   # 进入node目录
   cd node
   
   # 添加新包（开发依赖使用--save-dev）
   npm install --save <包名>
   
   # 添加特定版本的包
   npm install --save <包名>@1.0.0
   
   # 获取npm帮助
   npm help
   

3. 返回本地机器shell

   sh
   exit
   

4. 继续本地构建和测试。

本地构建和测试新镜像

1. 根据Python或Node依赖更新本地构建新镜像

   sh
   # 在本地机器shell中执行（非容器内）
   make images
   

   此命令将创建两个本地镜像：

   • texastribune/base:<git分支名>-dev
   • texastribune/base:<git分支名>-base

   可通过以下命令验证镜像是否创建成功：

   sh
   docker images | $(git branch --show-current)
   
   # 示例输出：
   texastribune/base          branchname-dev          2707ec0fcf6b        22分钟前      2.24GB
   texastribune/base          branchname-base         8a387eac996c        59分钟前      1.37GB
   

2. 本地测试

   • 切换到本地texastribune仓库：
     • 更新BASE_PRODUCTION_VERSION和BASE_DEVELOPMENT_VERSION变量
     • 参考texastribune文档了解更新方法，或使用文本编辑器搜索相关位置
   • 创建texastribune PR

3. 若测试通过，继续部署步骤。

部署

构建新基础镜像

如果是极小且不太可能影响他人的变更，可直接通过master分支构建新镜像；否则通过功能分支构建镜像。

直接通过master分支

1. 将变更提交到tt-base分支
2. 将该分支合并到master，然后继续部署texastribune步骤
3. 运行make bump命令并按照提示更新版本和创建标签，最后一个提示会将标签推送到远程。此步骤与上一步之间的间隔应尽可能短，以避免与其他提交者产生冲突
4. 继续部署texastribune步骤

通过tt-base功能分支

1. 将变更提交到tt-base功能分支

2. 推送分支：

   • Docker Hub将构建与本地构建同名的镜像
   • 此时任何人都可拉取并使用texastribune/base:<git分支名>镜像
   • 更新关联的texastribune PR，使用从tt-base功能分支构建的上述镜像。任何人都可拉取该PR分支进行本地测试
   • 可在https://hub.docker.com/repository/docker/texastribune/base%E6%9F%A5%E7%9C%8B%E6%9E%84%E5%BB%BA%E7%8A%B6%E6%80%81%E3%80%82%E7%99%BB%E5%BD%95Docker Hub中隶属于texastribune组织的账户可查看更准确的构建日志

3. 相关texastribune PR获批后，将tt-base功能分支合并到master并删除功能分支

4. 执行git checkout master和git pull使本地master分支与远程同步

5. 运行make bump命令并按照提示更新版本和创建标签，最后一个提示会将标签推送到远程。此步骤与上一步之间的间隔应尽可能短，以避免与其他提交者产生冲突

6. 继续部署texastribune步骤

部署texastribune

1. 将相关texastribune PR中的镜像引用从分支名改为标签（例如：texastribune/base:1.2.14-base和texastribune/base:1.2.14-dev）。参考texastribune README了解版本变更位置。建议等待Docker Hub完成镜像构建后再推送texastribune PR，否则CI测试会因镜像不可用而失败

2. 确保https://hub.docker.com/repository/docker/texastribune/base%E5%B7%B2%E6%9E%84%E5%BB%BA%E5%B8%A6%E6%A0%87%E7%AD%BE%E7%9A%84%E9%95%9C%E5%83%8F%E5%90%8E%E5%86%8D%E9%83%A8%E7%BD%B2%60texastribune%60 PR。紧急情况下可保留分支名——Docker Hub已构建的镜像即使分支删除也不会消失

3. 合并相关texastribune PR

4. 部署应用

5. 完成部署