vespaengine/vespa-build-centos7

Vespa开发Docker镜像

镜像概述和主要用途

本仓库包含用于Vespa开发的Docker镜像，分别基于AlmaLinux 8（Vespa 8）和CentOS 7（Vespa 7）。其中：

• https://hub.docker.com/repository/docker/vespaengine/vespa-build-almalinux-8 仅用于构建Vespa
• https://hub.docker.com/repository/docker/vespaengine/vespa-dev-almalinux-8 用于Vespa的主动开发，包括构建、单元测试和系统测试

vespa-dev-almalinux-8 依赖于 vespa-build-almalinux-8。

核心功能和特性

• 提供完整的Vespa开发环境，包含构建工具（mvn、cmake、make等）
• 支持代码编译、单元测试和系统测试
• 镜像自动构建：提交到master分支会自动触发Docker Hub上的新构建和部署
• 支持持久化存储，通过Docker卷或目录挂载保存开发数据
• 支持远程调试和X11转发，便于使用CLion或IntelliJ等IDE
• 支持Sanitizer工具（AddressSanitizer、ThreadSanitizer等）进行代码检测

使用场景和适用范围

适用于Vespa开发人员进行以下工作：

• Vespa核心代码的开发和调试
• Vespa模块的构建和单元测试
• 系统测试的执行和验证
• 针对不同CPU架构的优化构建
• 使用Sanitizer工具进行内存和线程安全检测

支持Vespa 8（基于AlmaLinux 8）和Vespa 7（基于CentOS 7）的开发。

详细使用方法和配置说明

拉取镜像

bash
docker pull docker.io/vespaengine/vespa-build-almalinux-8:latest
docker pull docker.io/vespaengine/vespa-dev-almalinux-8:latest

Vespa开发（AlmaLinux 8）

以下指南介绍如何使用Docker或Podman在AlmaLinux 8上构建、单元测试和系统测试Vespa。如果使用Podman，将命令中的docker替换为podman即可。

Docker配置

Docker on macOS

确保Docker拥有足够资源：

1. 打开Docker - 偏好设置 - 资源
2. 设置：
   • CPU：至少2核，8核或更多可加快构建速度
   • 内存：至少8GB，16GB或更多更佳
   • 磁盘大小：128GB

Docker on Linux

确保无需sudo即可执行Docker：

bash
sudo groupadd docker
sudo usermod -aG docker $(id -un)
sudo systemctl restart docker

注销并重新登录，或运行sudo su - $USER继续。

Podman on macOS

安装Podman Desktop：

bash
brew install podman-desktop

创建具有足够资源的Podman Machine（偏好设置 - 资源 - 创建新机器）：

• CPU：至少2核，8核或更多可加快构建速度
• 内存：至少8GB，16GB或更多更佳
• 磁盘大小：128GB
• 启用"具有root权限的机器"

也可通过命令行创建：

bash
podman machine init --cpus=8 --memory=16384 --disk-size=128 --rootful

容器设置

下载最新镜像

bash
docker pull docker.io/vespaengine/vespa-dev-almalinux-8:latest

创建容器

远程调试（可选）

如需附加远程调试器（如IntelliJ），需在创建容器时添加端口转发（容器创建后无法添加）。例如允许5005端口调试：

bash
-p 127.0.0.1:5005:5005 \

使用Docker卷（macOS推荐）

1. 创建持久卷（如已存在可跳过）：

bash
docker volume create volume-vespa-dev-almalinux-8

2. 创建容器，将卷挂载为容器内的主目录：

bash
docker create \
    -p 127.0.0.1:3334:22 \
    -v volume-vespa-dev-almalinux-8:/home/$(id -un) \
    --privileged \
    --pids-limit -1 \
    --name vespa-dev-almalinux-8 \
    docker.io/vespaengine/vespa-dev-almalinux-8:latest

使用目录挂载（Linux推荐）

1. 在主机创建卷目录：

bash
mkdir -p $HOME/volumes/vespa-dev-almalinux-8

2. 创建容器，将目录挂载为容器内的主目录：

bash
docker create \
    -p 127.0.0.1:3334:22 \
    -v $HOME/volumes/vespa-dev-almalinux-8:/home/$(id -un) \
    --privileged \
    --pids-limit -1 \
    --name vespa-dev-almalinux-8 \
    docker.io/vespaengine/vespa-dev-almalinux-8:latest

启动容器

bash
docker start vespa-dev-almalinux-8

配置容器

确保拥有SSH密钥（如无，参考https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent%EF%BC%89%EF%BC%9A

bash
mkdir -p $HOME/git
cd $HOME/git
git clone git@github.com:vespa-engine/docker-image-dev.git
cd $HOME/git/docker-image-dev/dev/almalinux-8
./configure-container.sh docker vespa-dev-almalinux-8

此脚本会添加用户、复制授权密钥并设置构建所需环境变量。

构建镜像（可选）

如需测试镜像修改：

bash
cd $HOME/git/docker-image-dev/dev/almalinux-8
docker build -t vespaengine/vespa-dev-almalinux-8:latest .

构建Vespa

SSH进入容器

bash
ssh -A 127.0.0.1 -p 3334

如SSH失败，参见SSH故障排除

克隆Vespa代码库

bash
mkdir -p $HOME/git
cd $HOME/git
git clone git@github.com:vespa-engine/vespa.git
cd $HOME/git/vespa

清理旧状态（如使用持久卷）

bash
git clean -fdx
ccache --clear

构建Java模块

bash
./bootstrap.sh java
mvn clean install --threads 1C -Dmaven.javadoc.skip=true -Dmaven.source.skip=true -DskipTests

构建C++模块

bash
cd $HOME/git/vespa
cmake3 .
make -j 9

编译线程数（-j参数）设置为CPU核心数+1。

针对新CPU架构优化构建

可使用-march=和-mtune=指定CPU架构，参考GCC手册。例如针对Haswell架构：

bash
cmake3 -DVESPA_CPU_ARCH_FLAGS="-march=haswell -mtune=skylake" .

安装模块

bash
make install/fast

默认安装目录为$HOME/vespa（$VESPA_HOME）。

运行单元测试

测试所有Java模块

bash
mvn test --threads 1C

测试特定Java模块（如container-search）

bash
mvn test --threads 1C -pl container-search

测试所有C++模块

bash
ctest -j 9

测试特定C++模块（如searchlib）

bash
ctest -j 9 -R "^searchlib_"

运行系统测试

克隆system-test代码库

bash
cd $HOME/git
git clone git@github.com:vespa-engine/system-test.git

系统测试脚本已在容器的PATH中。

复制功能标志覆盖配置

bash
cp $HOME/git/system-test/docker/include/feature-flags.json $HOME/vespa/var/vespa/flag.db

在一个终端启动nodeserver

bash
nodeserver.sh

在另一个终端运行系统测试

bash
cd $HOME/git/system-test/tests/search/basicsearch
runtest.sh basic_search.rb

使用Sanitizer工具构建和运行

Vespa支持使用https://github.com/google/sanitizers%E5%AF%B9C++%E4%BB%A3%E7%A0%81%E8%BF%9B%E8%A1%8C%E6%A3%80%E6%B5%8B%E3%80%82

使用Sanitizer构建C++代码

通过VESPA_USE_SANITIZER=sanitizer参数指定Sanitizer类型：

• address - AddressSanitizer
• thread - ThreadSanitizer
• undefined - UndefinedBehaviorSanitizer

一次只能使用一种Sanitizer。例如使用ThreadSanitizer：

bash
cmake3 -DVESPA_USE_SANITIZER=thread .

使用Sanitizer时不会构建vespamalloc，因为两者都会拦截malloc调用。

运行带Sanitizer的单元测试

可直接运行测试，如需循环运行特定测试（如检测偶发问题）：

bash
GTEST_FILTER=MyFlakyTestSuite.my_flaky_test_case;GTEST_REPEAT=100;TSAN_OPTIONS=halt_on_error=1;GTEST_FAIL_FAST=1

使用ThreadSanitizer时，需指定抑制文件：

bash
TSAN_OPTIONS="suppressions=/home/myuser/git/vespa/tsan-suppressions.txt"

运行带Sanitizer的系统测试

启动nodeserver前设置环境变量：

bash
export TSAN_OPTIONS="suppressions=/home/myuser/git/vespa/tsan-suppressions.txt log_path=/home/myuser/tsan_logs/log history_size=7 detect_deadlocks=1 second_deadlock_stack=1"
nodeserver.sh

故障排除

如启动时出现Sanitizer错误（如failed to intercept munmap），需清理安装目录并重新安装：

bash
rm -rf $HOME/vespa
make install/fast

在macOS上通过X11转发使用CLion或IntelliJ

安装XQuartz

下载并安装XQuartz。

配置容器内sshd使用ipv4

修改/etc/ssh/sshd_config：

AddressFamily inet

重启sshd：

bash
sudo kill -HUP <sshd-pid>

通过X11转发SSH进入容器

在XQuartz终端中运行：

bash
ssh -Y -A 127.0.0.1 -p 3334

然后从该终端启动CLion或IntelliJ。

SSH故障排除

如SSH失败（如ssh kex_exchange_identification: Connection closed by remote host）：

1. 进入容器交互shell：

bash
docker exec -it vespa-dev-almalinux-8 /bin/bash

2. 检查是否存在主机密钥：

bash
ls -l /etc/ssh

3. 如无ssh_host_*文件，生成主机密钥：

bash
sudo ssh-keygen -A

4. 启动sshd：

bash
$(which sshd)

如需进一步调试，可添加-Ddp参数启动sshd，并通过ssh -vvv查看详细日志。

Vespa 7开发（CentOS 7）

CentOS 7是Vespa 7（上一主要版本）的官方支持OS。如需在CentOS 7上构建、单元测试和系统测试Vespa，可按照AlmaLinux 8的指南操作，将命令中的almalinux-8替换为centos7即可。

许可证

本项目采用Apache License, Version 2.0许可。

更多信息

访问Vespa项目主页获取更多信息。