Principle:ClickHouse ClickHouse Package Validation

Knowledge Sources	ClickHouse
Domains	Packaging, Distribution
Last Updated	2026-02-08 00:00 GMT

Overview

Package validation is the practice of verifying that generated Linux distribution packages install correctly, resolve dependencies properly, place files in expected locations, and execute post-install scripts successfully.

Description

Generating a DEB or RPM package does not guarantee that it will install and function correctly on a target system. Package validation bridges the gap between package creation and production deployment by testing the installation process end-to-end. This includes verifying:

• Dependency resolution: All declared dependencies can be satisfied, and the package manager does not report unresolvable conflicts.
• File placement: Binaries, configuration files, symlinks, and documentation end up at the correct filesystem paths with appropriate permissions.
• Post-install script execution: Scripts that create users, set permissions, enable services, and configure directories complete without errors.
• Service readiness: Systemd units are correctly installed and the service can be started.
• Upgrade behavior: Configuration files with operator modifications are preserved, and package replacements/conflicts are handled cleanly.

For ClickHouse, package validation is particularly important because the packaging system uses nfpm (a non-traditional packaging tool), which bypasses some of the built-in validation that dpkg-deb and rpmbuild provide natively.

Usage

Package validation should be performed:

• In CI/CD pipelines after every package build, to catch regressions in packaging configuration.
• Before releasing a new ClickHouse version, as a gate in the release process.
• When modifying package YAML files, to verify that changes produce valid, installable packages.
• When testing on new target distributions, to verify compatibility with different package manager versions and system configurations.

Theoretical Basis

Installation Order and Dependencies

ClickHouse packages have a strict installation order dictated by their dependency declarations:

1. clickhouse-common-static must be installed first, as it contains the main clickhouse binary that all other packages depend on.
2. clickhouse-server and clickhouse-client can be installed in any order after the common package, as they depend on clickhouse-common-static but not on each other.
3. clickhouse-common-static-dbg and clickhouse-keeper-dbg are optional and can be installed at any time.

When using dpkg -i (low-level Debian installer), dependencies are not automatically resolved, so the installation order must be explicitly managed. Using apt install ./package.deb provides automatic dependency resolution. For RPM, rpm -i similarly requires manual ordering, while yum localinstall or dnf install handles dependencies automatically.

Validation Dimensions

Package validation covers multiple dimensions:

Structural Validation

• The package archive is well-formed and can be extracted.
• All declared files are present in the archive.
• File permissions and ownership are correct.
• Symlinks resolve to valid targets.

Dependency Validation

• All Depends packages are available and at compatible versions.
• Conflicts and Replaces declarations correctly handle upgrades from older versions.
• Provides declarations expose virtual packages for other packages to depend on.

Script Validation

• Post-install scripts exit with code 0.
• System users and groups are created correctly.
• Directories are created with proper ownership and permissions.
• Systemd units are enabled without errors.

Functional Validation

• The installed binary executes and responds to basic commands (e.g., clickhouse --version).
• The server starts and accepts connections.
• Symlink-based tools dispatch correctly (e.g., clickhouse-client --version).

DEB vs RPM Validation Differences

DEB and RPM packages have different validation behaviors:

Aspect	DEB (dpkg)	RPM (rpm)
Dependency checking	Warns but allows install with -i; strict with apt	Fails on unmet deps with rpm -i; resolved by yum/dnf
Config file handling	Uses conffiles and MD5 comparison	Uses %config(noreplace) flag
Script naming	postinst, prerm, etc.	%post, %preun, etc.
File verification	dpkg -V (limited)	rpm -V (checks size, MD5, permissions, etc.)

Idempotency of Post-Install Scripts

A well-designed post-install script is idempotent: running it multiple times produces the same result. This is critical because package managers may run post-install scripts during both fresh installs and upgrades. The ClickHouse server post-install script achieves idempotency by:

• Checking if directories exist before creating them.
• Using chown -R which is safe to re-run.
• Detecting the init system and adapting accordingly.
• Using clickhouse install which handles user/group creation idempotently.

Related Pages

Implemented By

• Implementation:ClickHouse_ClickHouse_Dpkg_Rpm_Install