Ruby CI Docker镜像文档

镜像概述

esparklearning/ruby-ci 是一个基于 CircleCI Ruby 镜像构建的 Docker 镜像，扩展集成了 QT4、FFPMEG、Node.js 及 Yarn 工具链。该镜像专为 Ruby 项目的持续集成/持续部署（CI/CD）场景设计，提供完整的构建、测试依赖环境。

• 镜像地址：Docker Hub
• 当前稳定版本：esparklearning/ruby-ci:2.6.3
• 基础镜像：CircleCI Ruby 官方镜像

核心功能与特性

基础能力

• 继承 CircleCI Ruby 镜像的原生 CI/CD 支持，包含 Ruby 运行环境、基础构建工具（如 gcc、make 等）及测试框架依赖。

扩展组件

• QT4：提供 GUI 应用测试支持（适用于需图形界面依赖的 Ruby 应用，如使用 Capybara 进行可视化测试场景）。
• FFPMEG：集成媒体文件处理能力，支持音频/视频格式转换、编解码等需求。
• Node.js/Yarn：内置 Node.js 运行环境及 Yarn 包管理器，满足前端依赖管理与构建需求（如 Ruby on Rails 项目中的前端资源编译）。

版本信息

• Ruby 版本：2.6.3（当前镜像版本对应）
• 依赖工具版本：继承自基础 CircleCI Ruby 镜像，具体可通过容器内 ruby -v、node -v、yarn -v 命令查看。

使用场景

适用范围

• Ruby 项目 CI/CD 流程：作为 CI 环境基础镜像，支持代码拉取、依赖安装（bundle install）、测试执行（rspec/minitest 等）、构建打包全流程。
• 多依赖场景：需同时处理 Ruby 后端逻辑、前端资源（Node.js/Yarn）、媒体文件（FFPMEG）或 GUI 测试（QT4）的全栈项目。
• 一致性环境：确保开发、测试、CI 环境依赖统一，避免"本地可运行，CI 失败"的环境差异问题。

使用方法与配置说明

拉取镜像

从 Docker Hub 拉取指定版本镜像：

docker pull esparklearning/ruby-ci:2.6.3

运行容器示例

1. 基础交互式测试

启动容器并进入交互式终端，验证环境依赖：

docker run -it --rm esparklearning/ruby-ci:2.6.3 /bin/bash

在容器内可执行以下命令检查组件版本：

ruby -v          # 验证 Ruby 版本
node -v          # 验证 Node.js 版本
yarn -v          # 验证 Yarn 版本
ffmpeg -version  # 验证 FFPMEG 版本
qmake -v         # 验证 QT4 版本（qmake 为 QT4 构建工具）

2. 挂载项目目录执行构建

将本地 Ruby 项目目录挂载到容器内，执行依赖安装与测试：

docker run -it --rm -v $(pwd):/app -w /app esparklearning/ruby-ci:2.6.3 \
  sh -c "bundle install && yarn install && rake test"

• -v $(pwd):/app：挂载当前目录到容器内 /app 路径
• -w /app：设置工作目录为 /app
• 命令链依次执行：Ruby 依赖安装（bundle install）、前端依赖安装（yarn install）、测试执行（rake test）

CI/CD 配置示例（CircleCI）

在 .circleci/config.yml 中指定该镜像作为构建环境：

version: 2.1
jobs:
  build-and-test:
    docker:
      - image: esparklearning/ruby-ci:2.6.3  # 使用本镜像作为基础环境
    steps:
      - checkout  # 拉取代码
      - restore_cache:  # 恢复缓存（可选，加速依赖安装）
          keys:
            - gem-cache-{{ checksum "Gemfile.lock" }}
            - yarn-cache-{{ checksum "yarn.lock" }}
      - run: bundle install --path vendor/bundle  # 安装 Ruby 依赖
      - run: yarn install --frozen-lockfile       # 安装前端依赖
      - save_cache:  # 保存缓存（可选）
          paths:
            - vendor/bundle
            - node_modules
          key: gem-cache-{{ checksum "Gemfile.lock" }}-yarn-{{ checksum "yarn.lock" }}
      - run: rake test  # 执行测试
      - run: rake build  # 执行构建（如生成 gem 包或部署产物）
workflows:
  version: 2
  ci-pipeline:
    jobs:
      - build-and-test

配置说明

• 环境变量：无特殊自定义环境变量，继承自基础 CircleCI Ruby 镜像（如 RUBY_VERSION、BUNDLE_PATH 等），可通过 docker run -e "VAR=value" 覆盖或添加自定义变量。
• 依赖管理：Ruby 依赖通过 Bundler 管理，前端依赖通过 Yarn 管理，工具链路径已默认配置（无需额外设置 PATH）。

构建新镜像

如需基于新版本 CircleCI Ruby 镜像更新本镜像，可按以下步骤操作：

前提条件

• 本地已安装 Docker 环境
• 拥有 Docker Hub esparklearning 仓库的推送权限
• 已更新 Dockerfile（基于目标 CircleCI Ruby 镜像版本，如 circleci/ruby:3.2.2）

构建步骤

1. 构建镜像
   执行 docker build 命令，指定版本标签：

   docker build -t ${VERSION} .
   

   其中 ${VERSION} 为目标版本号（如 3.2.2，需与基础 Ruby 版本匹配）。

2. 标记镜像
   将本地镜像标记为 Docker Hub 仓库格式：

   docker tag ${VERSION} esparklearning/ruby-ci:${VERSION}
   

3. 推送镜像
   推送标记后的镜像至 Docker Hub：

   docker push esparklearning/ruby-ci:${VERSION}
   

注意事项

• 镜像版本号与基础 Ruby 版本保持一致（如 2.6.3 对应 Ruby 2.6.3），便于版本管理。
• 扩展组件（QT4、FFPMEG 等）版本随基础镜像更新，如需固定版本需在 Dockerfile 中显式指定。
• 构建新镜像前建议验证基础 CircleCI Ruby 镜像兼容性，避免依赖冲突。