elixir-ci-docker 镜像文档

1. 镜像概述

elixir-ci-docker 是一个专为持续集成(CI)流程设计的 Docker 镜像，主要用于在 CI 环境中自动化执行 Elixir 应用的构建、测试及相关任务。该镜像预配置了 Elixir 开发和测试所需的核心工具链，确保在 CI 流程中能够快速、一致地运行 Elixir 项目的构建和验证步骤。

镜像构建及版本管理托管于 DockerHub，地址：[***]

2. 核心功能与特性

• 完整的 Elixir 运行环境：内置指定版本的 Elixir 解释器及标准库，满足 Elixir 应用运行需求。
• Mix 工具链集成：包含 Elixir 项目构建工具 Mix，支持依赖管理（mix deps.get）、项目编译（mix compile）、测试执行（mix test）等核心操作。
• Hex 包管理器：预安装 Hex（Elixir 包管理工具），支持自动拉取项目依赖。
• CI 环境适配：优化非交互式运行配置，支持在 CI 系统（如 GitLab CI、GitHub Actions、Jenkins 等）中无交互执行任务。
• 版本稳定性：通过 DockerHub 自动化构建流程维护，确保镜像版本与 Elixir ***版本同步，减少环境差异导致的构建失败。

3. 使用场景与适用范围

适用场景

• CI/CD 流程中的构建环节：在 CI 管道中自动执行 Elixir 项目的依赖安装、代码编译。
• 自动化测试执行：在 CI 环境中运行单元测试、集成测试等，生成测试报告。
• 多环境一致性验证：确保开发、测试、CI 环境中 Elixir 版本及依赖一致，避免“在我机器上能运行”问题。

适用范围

• 所有基于 Elixir 开发的应用项目（包括 Phoenix 框架应用）。
• 需在 CI/CD 平台（如 GitHub Actions、GitLab CI/CD、Jenkins、Travis CI 等）中自动化执行构建、测试步骤的场景。

4. 使用方法与配置说明

4.1 镜像拉取

从 DockerHub 拉取最新版本镜像：

docker pull smartrent/elixir-ci:latest

如需指定版本，可通过标签拉取（具体标签参见 DockerHub 仓库）：

docker pull smartrent/elixir-ci:1.15.7  # 示例：拉取 Elixir 1.15.7 版本镜像

4.2 基本使用（本地模拟 CI 环境）

在本地环境中挂载 Elixir 项目目录，执行测试命令（模拟 CI 流程）：

# 假设项目代码位于当前目录下的 ./my_elixir_app
docker run --rm -v $(pwd)/my_elixir_app:/app -w /app smartrent/elixir-ci:latest \
  sh -c "mix deps.get && mix test"

• -v $(pwd)/my_elixir_app:/app：将本地项目目录挂载到容器内 /app 路径。
• -w /app：指定容器工作目录为 /app（项目根目录）。
• mix deps.get && mix test：依次执行依赖安装和测试命令。

5. Docker 部署示例

5.1 基本 docker run 命令示例（CI 环境执行测试）

在 CI 脚本中使用以下命令执行项目测试：

docker run --rm \
  -v $CI_PROJECT_DIR:/app \  # 挂载 CI 项目目录（变量名因 CI 平台而异，如 GitHub Actions 为 $GITHUB_WORKSPACE）
  -w /app \
  -e MIX_ENV=test \  # 指定 Mix 环境为测试环境
  smartrent/elixir-ci:latest \
  mix test --cover  # 执行测试并生成覆盖率报告

5.2 docker-compose 配置示例（本地开发/测试）

创建 docker-compose.yml 文件，用于本地模拟 CI 环境：

version: '3.8'
services:
  elixir-ci:
    image: smartrent/elixir-ci:latest
    volumes:
      - ./:/app  # 挂载本地项目目录
    working_dir: /app
    environment:
      - MIX_ENV=test  # 测试环境
      - HEX_MIRROR=[***]  # 可选：指定 Hex 镜像源（加速依赖拉取）
    command: sh -c "mix deps.get && mix compile && mix test"

启动容器执行测试：

docker-compose up

5.3 CI 配置文件示例（GitLab CI/CD）

在项目根目录创建 .gitlab-ci.yml，使用该镜像定义测试阶段：

stages:
  - test

elixir-test:
  stage: test
  image: smartrent/elixir-ci:latest
  script:
    - mix deps.get --only test  # 拉取测试环境依赖
    - mix test --trace  # 执行测试并输出详细日志
  cache:
    paths:
      - deps/  # 缓存依赖，加速后续构建
      - _build/

6. 配置参数与环境变量

7. 镜像构建与更新

• 构建地址：镜像通过 DockerHub 自动构建，构建状态及历史版本可在 DockerHub 仓库 查看。
• 更新策略：当 Elixir ***发布新版本或镜像依赖（如 Erlang/OTP 版本）更新时，DockerHub 会自动触发构建并更新 latest 标签及版本标签。
• 版本兼容：建议在 CI 配置中指定具体版本标签（如 1.15.7），避免因 latest 标签自动更新导致环境变更。