XWiki Build Docker 镜像文档

一、镜像概述和主要用途

XWiki Build 镜像为XWiki项目定制，主要用于为 [] 生成Jenkins代理，同时也支持在任何安装Docker的机器上构建XWiki项目。该镜像基于Jenkins提供的 jenkins/ssh-slave 基础镜像构建，补充了XWiki构建所需的特定工具链。

二、核心功能和特性

在 jenkins/ssh-slave 基础镜像之上，该镜像添加了以下XWiki构建必需的工具：

• VNC服务器：支持图形化测试环境
• Docker客户端：用于运行基于Docker的测试（支持Docker外的Docker/DOOD）
• Java 8环境：采用Amazon Corretto版本
• Firefox浏览器：
  • 32.0.1版本：用于基于Selenium-2的功能测试
  • 较新版本：用于基于Selenium-3的功能测试（尚未迁移至Docker测试的场景）

该镜像通过 Docker Hub 自动构建。

三、使用场景和适用范围

1. CI环境

• 作为Jenkins代理节点，部署于 [***] 构建系统
• 执行XWiki项目的自动化构建、测试流程（包括Maven构建、Selenium功能测试、Docker测试等）

2. 本地环境

• 复现CI环境中的构建问题
• 本地构建XWiki项目，无需手动配置完整的依赖环境

四、详细使用方法和配置说明

1. CI环境使用

1.1 ci.xwiki.org配置

前置条件： 在代理机器上需存在以下文件/目录（详见下方说明）：

• /home/hudsonagent/.m2/settings.xml
• /home/hudsonagent/.ssh

Docker云配置：

• Docker主机URI：tcp://<代理主机IP>:2376
• 镜像：xwiki/build
• 卷挂载：

  /var/run/docker.sock:/var/run/docker.sock
  /home/hudsonagent/.m2/settings.xml:/root/.m2/settings.xml
  /home/hudsonagent/.ssh:/tmp/xwiki/.ssh:ro
  /home/hudsonagent/.xwiki:/root/.xwiki
  

  卷挂载说明：
  • /var/run/docker.sock:/var/run/docker.sock：允许Docker外的Docker（DOOD），支持功能测试中使用Docker容器
  • /home/hudsonagent/.m2/settings.xml:/root/.m2/settings.xml：提供Maven仓库配置（用于获取非中央仓库 artifacts）及插件所需凭据
  • /home/hudsonagent/.ssh:/tmp/xwiki/.ssh:ro：支持Jenkins流水线（如Clover）向网络中其他机器发布输出（如向 maven.xwiki.org 发布Clover报告），ro 表示只读
  • /home/hudsonagent/.xwiki:/root/.xwiki：存储XWiki Docker测试框架的缓存文件，避免频繁从DockerHub拉取镜像（DockerHub有每6小时100-200次的拉取限制）
• 远程文件系统根目录：/root
• 用户：root

1.2 CI代理上的手动执行

若需登录CI代理节点复现问题并手动执行构建，步骤如下：

1. SSH连接至代理节点
2. 启动Docker代理容器：

   bash
   docker run -d --rm -v /var/run/docker.sock:/var/run/docker.sock -v /home/hudsonagent/.m2/settings.xml:/root/.m2/settings.xml -v /home/hudsonagent/.ssh:/tmp/xwiki/.ssh:ro xwiki/build
   

3. 进入容器shell：

   bash
   docker exec -it <容器ID> bash -l
   

4. 克隆代码仓库（示例）：

   bash
   git clone [***]
   

5. 执行Maven构建（示例）：

   bash
   cd xwiki-platform/<具体路径>; mvn clean install
   

   • Docker测试示例：在目录 ~/xwiki-platform/xwiki-platform-core/xwiki-platform-annotation/xwiki-platform-annotation-test/xwiki-platform-annotation-test-docker 中执行：

     bash
     mvn clean integration-test -Dxwiki.checkstyle.skip=true -Dxwiki.surefire.captureconsole.skip=true -Dxwiki.revapi.skip=true -Dmaven.build.dir=target/mysql-5.7-5.1.45-tomcat-8.5-chrome -Dxwiki.test.ui.database=mysql -Dxwiki.test.ui.databaseTag=5.7 -Dxwiki.test.ui.jdbcVersion=5.1.45 -Dxwiki.test.ui.servletEngine=tomcat -Dxwiki.test.ui.servletEngineTag=8.5 -Dxwiki.test.ui.browser=chrome -Dxwiki.test.ui.verbose=true
     

6. 若构建需VNC：启动VNC服务器并设置显示变量：

   bash
   vncserver :1 -geometry 1280x960 -localhost -nolisten tcp
   export DISPLAY=:1
   

7. 完成后停止容器：

   bash
   docker stop <容器ID>
   

2. 本地环境使用

本地使用适用于复现CI问题或搭建本地XWiki构建环境，仅需安装Docker。

2.1 所有操作系统通用

2.1.1 交互模式

适用于最小化构建配置，模拟CI代理环境：

bash
docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --entrypoint "/bin/bash" xwiki/build

进入容器后操作：

1. 克隆代码仓库（示例）：

   bash
   git clone [***]
   

2. 进入目标目录执行Maven命令

注意：

• 如需映射本地Maven仓库或其他配置，详见下文高级选项
• 执行基于Selenium2的功能测试需设置DISPLAY，否则会报错（如 Caused by: org.openqa.selenium.WebDriverException: invalid argument: can't kill an exited process）

2.1.2 脚本模式

一次性执行完整构建流程（示例：构建整个XWiki Platform，含功能测试）：

bash
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock --entrypoint "/bin/bash" xwiki/build -c " \
git clone [***] && \
cd xwiki-platform && \
export MAVEN_OPTS='-Xmx2048m -Xms512m' && \
vncserver :1 -geometry 1280x960 -localhost -nolisten tcp && \
export DISPLAY=:1 && \
/home/hudsonagent/maven/bin/mvn --no-transfer-progress install -Plegacy,integration-tests,docker,snapshot \
"

2.2 macOS系统

以下步骤配置GUI显示（需先参考 教程 安装必要工具）：

1. 启动socat转发显示端口：

   bash
   socat TCP-LISTEN:6000,reuseaddr,fork UNIX-CLIENT:\"$DISPLAY\"
   

2. 打开XQuartz：

   bash
   open -a Xquartz
   

3. 获取本地IP：

   bash
   IP=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')
   

4. 进入本地Maven模块目录，启动容器：

   bash
   docker run -d --rm \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v $HOME/.m2:/root/.m2:delegated \
     -v $HOME/.git-credentials:/root/.git-credentials \
     -v $HOME/.git-gitconfig:/root/.git-gitconfig \
     -v $HOME/.gitconfig:/root/.gitconfig \
     -v $HOME/.gitignore_global:/root/.gitignore_global \
     -v $HOME/.ssh:/tmp/xwiki/.ssh:ro \
     -v $HOME/.gnupg:/root/.gnupg \
     -v `pwd`:/root/`basename \`pwd\``:delegated \
     -e DISPLAY=$IP:0 -p 8080:8080 --privileged xwiki/build
   

参数说明：

• delegated：优化macOS下卷挂载性能（参考 Docker for Mac文档）
• /var/run/docker.sock:/var/run/docker.sock：支持Docker-in-Docker
• $HOME/.m2:/root/.m2:delegated：复用本地Maven仓库，避免重复下载依赖
• .git* 挂载：映射本地Git配置至容器
• $HOME/.ssh:/tmp/xwiki/.ssh:ro：映射SSH密钥（容器启动脚本会自动复制至 /root/.ssh 并设置权限）
• $HOME/.gnupg:/root/.gnupg：映射GPG密钥（用于Maven发布等场景）
• -e DISPLAY=$IP:0：转发显示至本地XQuartz
• -p 8080:8080：映射端口，允许本地访问容器内XWiki实例
• --privileged：特权模式（部分场景可能需要）

2.3 Linux系统

与macOS类似，但需添加X11转发参数以支持GUI显示：

bash
sudo docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $HOME/.m2:/root/.m2:delegated \
  -v $HOME/.git-credentials:/root/.git-credentials \
  -v $HOME/.git-gitconfig:/root/.git-gitconfig \
  -v $HOME/.gitconfig:/root/.gitconfig \
  -v $HOME/.gitignore_global:/root/.gitignore_global \
  -v $HOME/.ssh:/tmp/xwiki/.ssh:ro \
  -v $HOME/.gnupg:/root/.gnupg \
  -v `pwd`:/root/`basename \`pwd\``:delegated \
  -p 8080:8080 \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v $XAUTHORITY:/root/.Xauthority \
  -e DISPLAY \
  --net=host \
  --entrypoint "/bin/bash" \
  xwiki/build

X11转发必需参数（支持容器内Firefox窗口显示）：

  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v $XAUTHORITY:/root/.Xauthority \
  -e DISPLAY \
  --net=host \

2.3.1 构建示例

• 执行单个Selenium测试类（如"Flavor Test - UI"步骤，Firefox窗口通过X11转发显示）：

  bash
  # 进入测试模块目录
  cd ~/xwiki-platform/xwiki-platform-distribution/xwiki-platform-distribution-flavor/xwiki-platform-distribution-flavor-test/xwiki-platform-distribution-flavor-test-ui
  # 执行测试
  mvn clean install -Plegacy,integration-tests,jetty,hsqldb,firefox -Dpattern=UserClassFieldTest
  

• 执行"Flavor Test - Upgrade"测试：

  bash
  # 进入升级测试模块目录
  cd ~/xwiki-platform/xwiki-platform-distribution/xwiki-platform-distribution-flavor/xwiki-platform-distribution-flavor-test/xwiki-platform-distribution-flavor-test-upgrade/xwiki-platform-distribution-flavor-test-upgrade-1011
  # 执行测试
  mvn clean install -Plegacy,integration-tests,jetty,hsqldb,firefox
  

• 执行Docker测试（Firefox运行于Docker-in-Docker容器，需通过VNC客户端连接容器内VNC服务器查看）：

  bash
  # 进入Docker测试模块目录
  cd ~/xwiki-platform/xwiki-platform-core/xwiki-platform-flamingo/xwiki-platform-flamingo-theme/xwiki-platform-flamingo-theme-test/
  # 执行测试
  mvn clean install -Plegacy,integration-tests,snapshot,docker -Dxwiki.checkstyle.skip=true -Dxwiki.surefire.captureconsole.skip=true -Dxwiki.revapi.skip=true