gastrupul/circleci-ruby-headless-3.4.1

镜像概述

本镜像为基于Ruby 3.4.1版本的Docker环境镜像，专为PathLMS项目在CircleCI持续集成平台中设计与优化。旨在为PathLMS项目提供一致、稳定的Ruby运行时环境，确保项目在CI流程中的构建、测试及部署环节能够高效、可靠地执行，减少因环境差异导致的构建失败问题。

核心功能和特性

• Ruby 3.4.1运行时：内置Ruby 3.4.1版本，包含完整的Ruby标准库及运行环境，满足PathLMS项目对Ruby版本的依赖需求。
• CircleCI平台优化：针对CircleCI的容器运行环境进行适配，包含常见CI流程所需的系统依赖（如git、curl、build-essential等），减少额外依赖安装步骤。
• 环境一致性：通过Docker镜像封装，确保开发、测试及CI环境的Ruby版本及依赖配置统一，避免"在我机器上能运行"的问题。
• 便捷集成：支持直接作为CircleCI job的执行环境，无需复杂配置即可接入现有CI流程。
• 轻量级设计：在保证功能完整性的前提下，基于精简基础镜像构建，减少镜像体积，提升CI流程启动速度。

使用场景和适用范围

• PathLMS项目CI/CD流程：适用于PathLMS项目在CircleCI中的自动化构建、单元测试、集成测试及部署前验证等环节。
• 开发环境复现：开发团队可在本地通过该镜像复现CI环境中的问题，便于调试构建或测试失败场景。
• 多环境一致性保障：确保开发、测试、CI及预发布环境使用相同的Ruby版本及依赖配置，降低环境差异带来的风险。
• 团队协作标准化：为团队提供统一的Ruby开发环境模板，新成员可快速接入项目开发，无需手动配置复杂依赖。

使用方法和配置说明

本地测试与运行

如需在本地环境测试或复现CI流程，可通过以下命令启动容器：

bash
# 挂载当前项目目录并执行bundle install
docker run --rm -v $(pwd):/app -w /app docker.xuanyuan.run/pathlms/ruby:3.4.1-circleci bundle install

# 运行项目测试
docker run --rm -v $(pwd):/app -w /app docker.xuanyuan.run/pathlms/ruby:3.4.1-circleci bundle exec rake test

参数说明：

• --rm：容器退出后自动删除，避免残留容器占用资源。
• -v $(pwd):/app：将本地当前目录挂载到容器内的/app目录，实现代码实时同步。
• -w /app：设置容器工作目录为/app，即项目根目录。

CircleCI配置集成

在PathLMS项目的CircleCI配置文件（.circleci/config.yml）中，可直接将本镜像指定为执行环境。以下为基础配置示例：

yaml
version: 2.1

jobs:
  build-and-test:
    docker:
      - image: pathlms/ruby:3.4.1-circleci  # 使用本镜像作为执行环境
    steps:
      - checkout  # 拉取代码
      - restore_cache:  # 恢复bundle缓存（如配置了缓存）
          keys:
            - bundle-{{ checksum "Gemfile.lock" }}
            - bundle-
      - run: bundle install --path vendor/bundle  # 安装依赖
      - save_cache:  # 保存bundle缓存
          paths:
            - vendor/bundle
          key: bundle-{{ checksum "Gemfile.lock" }}
      - run: bundle exec rake test  # 执行测试命令
      - run: bundle exec rake build  # 执行构建命令（如适用）

workflows:
  version: 2
  build-test-deploy:
    jobs:
      - build-and-test

环境变量配置

本镜像支持通过环境变量自定义运行参数，常用环境变量如下：

可在CircleCI配置中通过environment字段设置环境变量：

yaml
jobs:
  build-and-test:
    docker:
      - image: pathlms/ruby:3.4.1-circleci
    environment:
      RUBY_ENV: "test"
      BUNDLE_JOBS: "8"  # 增加并行任务数，加速依赖安装
    steps:
      # ... 步骤省略 ...

注意事项

1. 镜像更新：建议定期检查镜像更新，确保使用最新版本以获取安全补丁及依赖更新。
2. 依赖管理：项目的Gemfile.lock应纳入版本控制，确保CI环境安装的依赖版本与开发环境一致。
3. 缓存优化：在CircleCI配置中启用bundle缓存（如示例所示），可大幅减少依赖安装时间，提升CI流程效率。
4. 系统依赖：如项目需额外系统依赖（非RubyGems依赖），可通过run步骤在CI流程中安装，例如：

   yaml
   - run: sudo apt-get update && sudo apt-get install -y libpq-dev  # 安装PostgreSQL客户端依赖