Environment:ClickHouse ClickHouse CI Docker Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, CI_CD |
| Last Updated | 2026-02-08 18:00 GMT |
Overview
Docker-based CI environment running the Praktika framework for automated ClickHouse build verification, testing, and packaging across multiple build configurations.
Description
The ClickHouse CI pipeline runs inside Docker containers orchestrated by the Praktika framework (a Python package defined in `ci/setup.py`). CI containers include pre-configured toolchains (Clang 21+, CMake 3.25+, Ninja), sanitizer runtimes, and a custom `ld.lld` wrapper that works around a Clang bug with `.debug_aranges` and ThinLTO. The CI runs multiple build configurations including Release, Debug, ASan, TSan, MSan, UBSan, and fuzzing builds.
Usage
Use this environment when running CI jobs or reproducing CI failures locally. It is required for the Praktika CI Framework implementation and the Contributing Pull Request workflow. When debugging CI issues, prefer Praktika reports over GitHub Actions logs, as they provide more detailed information.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux (Docker host) | CI containers are Linux-based |
| Software | Docker | Required to run CI containers locally |
| RAM | 16GB+ | Multiple build configurations run in parallel; sanitizer builds require extra memory |
| Disk | 100GB+ SSD | Multiple build directories, ccache, Docker images |
Dependencies
System Packages (inside CI container)
- `clang` >= 21
- `lld` (with custom wrapper for ThinLTO `.debug_aranges` bug)
- `cmake` >= 3.25
- `ninja-build`
- `git`
- `docker`
- `python3`
- `nfpm` (for package generation)
Python Packages
- `praktika` (ClickHouse CI framework, from `ci/setup.py`)
Credentials
The following environment variables may be needed for CI operations:
- `GITHUB_TOKEN`: For GitHub API operations (PR comments, status updates)
- `S3_ACCESS_KEY_ID`: For uploading build artifacts and test reports to S3
- `S3_SECRET_ACCESS_KEY`: For S3 artifact storage
Quick Install
# Install Praktika CI framework locally
cd ClickHouse
pip install -e ci/
# Run integration tests locally
python -m ci.praktika run "integration" --test <selectors>
Code Evidence
Praktika package definition from `ci/setup.py:1-17`:
from setuptools import setup, find_packages
setup(
name="praktika",
version="0.1",
packages=find_packages(),
)
Custom LLD wrapper note from `CMakeLists.txt:304-306`:
# NOTE: that clang has a bug because of it does not emit .debug_aranges
# with ThinLTO, so custom ld.lld wrapper is shipped in docker images.
set(DEBUG_INFO_FLAGS "${DEBUG_INFO_FLAGS} -gdwarf-aranges")
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| CI report shows failures not in GitHub Actions | Praktika reports have more detail | Check Praktika reports first, not GitHub Actions logs |
| `addr2line` slow on CI artifacts | Missing `.debug_aranges` due to ThinLTO bug | Use the custom `ld.lld` wrapper shipped in CI Docker images |
| Build OOM in CI | Sanitizer builds consume 2-3x memory | Reduce parallel link jobs; ThinLTO limited to max 2 link jobs |
Compatibility Notes
- Local reproduction: Use `python -m ci.praktika run` from the repository root to reproduce CI jobs locally.
- Praktika vs GitHub Actions: Praktika reports contain more detailed test logs. Always check robot comments on PRs for Praktika report links first.
- Build configurations: CI runs Release, Debug, ASan, TSan, MSan, UBSan, and fuzzing builds. Each has different memory requirements and feature flags.