xwiki/xwiki-jenkins-slave

XWiki Build Docker镜像文档

镜像概述和主要用途

本镜像为XWiki项目的自定义Docker镜像，基于Jenkins提供的https://hub.docker.com/r/jenkinsci/ssh-slave%E5%9F%BA%E7%A1%80%E9%95%9C%E5%83%8F%E6%9E%84%E5%BB%BA%E3%80%82%E4%B8%BB%E8%A6%81%E7%94%A8%E4%BA%8E%E4%B8%BAhttps://ci.xwiki.org%E7%94%9F%E6%88%90Jenkins%E4%BB%A3%E7%90%86%EF%BC%8C%E5%90%8C%E6%97%B6%E4%B9%9F%E5%8F%AF%E5%9C%A8%E4%BB%BB%E4%BD%95%E5%AE%89%E8%A3%85Docker%E7%9A%84%E6%9C%BA%E5%99%A8%E4%B8%8A%E6%9E%84%E5%BB%BAXWiki%E9%A1%B9%E7%9B%AE%E3%80%82

该镜像通过Dockerhub自动构建，可从https://hub.docker.com/r/xwiki/build%E8%8E%B7%E5%8F%96%E3%80%82

核心功能和特性

在基础镜像之上，添加了XWiki构建所需的以下工具：

• VNC服务器：支持图形化测试环境
• Docker客户端：用于运行基于Docker的测试
• 最新Java 8版本（Amazon Corretto）：满足构建环境需求
• Firefox 32.0.1：用于运行基于Selenium-2的功能测试
• 较新版本Firefox：用于运行尚未迁移到Docker测试的Selenium-3功能测试

使用场景和适用范围

• CI/CD环境：作为Jenkins代理，用于xwiki.org持续集成系统
• 问题排查：在CI代理上手动执行构建以复现问题
• 本地开发：在个人机器上搭建一致的XWiki构建环境，复现CI问题或简化本地构建流程

使用方法和配置说明

CI环境使用

ci.xwiki.org配置

1. 代理机器准备：确保代理机器上存在以下文件/目录：

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

2. 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-out-of-Docker (DOOD)，允许运行基于Docker的功能测试
     • /home/hudsonagent/.m2/settings.xml:/root/.m2/settings.xml：提供Maven中央仓库外的 artifact 仓库配置及插件所需凭证
     • /home/hudsonagent/.ssh:/tmp/xwiki/.ssh:ro：允许Jenkins流水线（如Clover）向网络中其他机器发布输出（如向maven.xwiki.org发布Clover报告）
     • /home/hudsonagent/.xwiki:/root/.xwiki：存储XWiki Docker测试框架的缓存文件，避免频繁从DockerHub拉取镜像（受DockerHub拉取限制）
   • 远程文件系统根目录：/root
   • 用户：root

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 https://github.com/xwiki/xwiki-platform.git
   
   # Maven构建示例（进入对应目录）
   cd xwiki-platform/<具体路径>; mvn clean install
   
   # Docker测试示例
   cd xwiki-platform/xwiki-platform-core/xwiki-platform-annotation/xwiki-platform-annotation-test/xwiki-platform-annotation-test-docker
   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
   

5. 如需VNC支持：

   bash
   # 启动VNC服务器
   vncserver :1 -geometry 1280x960 -localhost -nolisten tcp
   
   # 设置显示环境变量
   export DISPLAY=:1
   

6. 完成后停止容器：

   bash
   docker stop <容器ID>
   

本地环境使用

可用于在本地机器复现CI问题或搭建简单的XWiki构建环境（仅需安装Docker）。

所有操作系统通用

交互模式

如需最小化构建设置并模拟CI代理环境：

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

进入容器后：

1. 克隆代码仓库：

   bash
   git clone https://github.com/xwiki/xwiki-platform.git
   

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

注意：

• 如需映射本地Maven仓库或其他配置，参见下文
• 运行基于Selenium2的功能测试需设置DISPLAY，否则会出现类似Caused by: org.openqa.selenium.WebDriverException: invalid argument: can't kill an exited process的错误

脚本模式

如需一次性执行完整构建（含功能测试）：

bash
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock --entrypoint "/bin/bash" xwiki/build -c " \
git clone https://github.com/xwiki/xwiki-platform.git && \
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 \
"

Mac系统

以下步骤实现镜像运行并在Mac上显示GUI（需先按照tutorial安装必要工具）：

bash
# 设置显示转发
socat TCP-LISTEN:6000,reuseaddr,fork UNIX-CLIENT:\"$DISPLAY\"
open -a Xquartz
IP=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')

# 进入本地Maven模块目录
cd ...导航至包含pom.xml的本地目录...

# 启动容器
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：优化卷挂载性能（解决Mac上osxfs性能问题）
• -v /var/run/docker.sock:/var/run/docker.sock：支持Docker-in-Docker
• -v $HOME/.m2:/root/.m2:delegated：复用本地Maven仓库，避免重复下载依赖
• .git*卷映射：将本地Git配置导入容器
• -v $HOME/.ssh:/tmp/xwiki/.ssh:ro：提供SSH密钥（容器启动脚本会将其复制到/root/.ssh并设置权限）
• -v $HOME/.gnupg:/root/.gnupg：提供GPG密钥（如执行Maven发布时需要）
• -v pwd:/root/basename `pwd`:delegated：挂载本地代码目录，避免重新克隆
• -e DISPLAY=$IP:0：将显示转发到Mac
• -p 8080:8080：允许通过http://localhost:8080访问容器内XWiki实例
• --privileged：特殊权限模式（部分场景可能需要）

Linux系统

与Mac类似，但启动容器时需添加X11转发参数：

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 \

示例

执行"Flavor Test - UI"构建步骤中的单个Selenium测试类（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