Implementation:ClickHouse ClickHouse Nfpm Common Static Package

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

Overview

Concrete tool for generating the clickhouse-common-static DEB and RPM packages provided by the nfpm external packaging tool and its YAML configuration.

Description

The clickhouse-common-static package is the foundation package of the ClickHouse distribution. It contains the main statically-linked clickhouse binary, the clickhouse-extract-from-config utility, bash completion scripts, and documentation files. All other ClickHouse packages depend on this one.

The package is defined in a YAML file that nfpm reads to produce either DEB or RPM output. The YAML file uses environment variable interpolation for version and architecture, making it reusable across builds. Package sources (the actual files to include) are placed in a root/ subdirectory adjacent to the YAML file, mirroring the target filesystem layout.

The package declares that it replaces and provides the legacy clickhouse-common and clickhouse-server-base packages, ensuring smooth upgrades from older ClickHouse packaging schemes. It also suggests the clickhouse-common-static-dbg package for users who need debug symbols.

Usage

Use this package configuration when building ClickHouse distribution packages. The nfpm tool should be invoked from the packages/ directory with the package sources staged in the root/ subdirectory.

Code Reference

Source Location

• Repository: ClickHouse
• File: packages/clickhouse-common-static.yaml (lines 1--51)

Signature

name: "clickhouse-common-static"
arch: "${DEB_ARCH}"          # amd64, arm64
platform: "linux"
version: "${CLICKHOUSE_VERSION_STRING}"
vendor: "ClickHouse Inc."
homepage: "https://clickhouse.com"
license: "Apache"
section: "database"
priority: "optional"
maintainer: "ClickHouse Dev Team <packages+linux@clickhouse.com>"

replaces:
- clickhouse-common
- clickhouse-server-base
provides:
- clickhouse-common
- clickhouse-server-base
suggests:
- clickhouse-common-static-dbg

contents:
- src: root/usr/bin/clickhouse
  dst: /usr/bin/clickhouse
- src: root/usr/bin/clickhouse-extract-from-config
  dst: /usr/bin/clickhouse-extract-from-config
- src: root/usr/share/bash-completion/completions
  dst: /usr/share/bash-completion/completions
- src: root/usr/share/clickhouse
  dst: /usr/share/clickhouse
- src: ../AUTHORS
  dst: /usr/share/doc/clickhouse-common-static/AUTHORS
- src: ../CHANGELOG.md
  dst: /usr/share/doc/clickhouse-common-static/CHANGELOG.md
- src: ../LICENSE
  dst: /usr/share/doc/clickhouse-common-static/LICENSE
- src: ../README.md
  dst: /usr/share/doc/clickhouse-common-static/README.md

API

# Generate DEB package:
nfpm package -p deb -f clickhouse-common-static.yaml

# Generate RPM package:
nfpm package -p rpm -f clickhouse-common-static.yaml

I/O Contract

Inputs

Name	Type	Required	Description
root/usr/bin/clickhouse	ELF binary	Yes	The stripped, statically-linked ClickHouse binary
root/usr/bin/clickhouse-extract-from-config	Script/binary	Yes	Utility for extracting values from ClickHouse XML configuration files
root/usr/share/bash-completion/completions	Directory	Yes	Bash completion scripts for ClickHouse commands
root/usr/share/clickhouse	Directory	Yes	Shared data files for ClickHouse
../AUTHORS	Text file	Yes	Project authors list
../CHANGELOG.md	Text file	Yes	Project changelog
../LICENSE	Text file	Yes	Apache 2.0 license text
../README.md	Text file	Yes	Project readme
${CLICKHOUSE_VERSION_STRING}	Environment variable	Yes	Version string (e.g., 24.3.1.1)
${DEB_ARCH}	Environment variable	Yes	Target architecture (e.g., amd64, arm64)

Outputs

Name	Type	Description
clickhouse-common-static_${VERSION}_${ARCH}.deb	Debian package	DEB package containing the main ClickHouse binary and support files, installable via dpkg -i or apt install
clickhouse-common-static-${VERSION}.${ARCH}.rpm	RPM package	RPM package with equivalent contents, installable via rpm -i or yum install

Installed File Layout

The package installs the following files on the target system:

/usr/bin/clickhouse                                     # Main binary
/usr/bin/clickhouse-extract-from-config                 # Config extraction utility
/usr/share/bash-completion/completions/                 # Bash completions
/usr/share/clickhouse/                                  # Shared data
/usr/share/doc/clickhouse-common-static/AUTHORS         # Documentation
/usr/share/doc/clickhouse-common-static/CHANGELOG.md
/usr/share/doc/clickhouse-common-static/LICENSE
/usr/share/doc/clickhouse-common-static/README.md

Usage Examples

Building the package

# Set required environment variables:
export CLICKHOUSE_VERSION_STRING="24.3.1.1"
export DEB_ARCH="amd64"

# Stage the binary and support files:
mkdir -p packages/root/usr/bin
cp build/programs/clickhouse packages/root/usr/bin/clickhouse
cp programs/extract-from-config/clickhouse-extract-from-config \
   packages/root/usr/bin/clickhouse-extract-from-config

# Generate the DEB package:
cd packages
nfpm package -p deb -f clickhouse-common-static.yaml

# Generate the RPM package:
nfpm package -p rpm -f clickhouse-common-static.yaml

Inspecting the generated package

# List contents of the DEB:
dpkg-deb -c clickhouse-common-static_24.3.1.1_amd64.deb

# Show package metadata:
dpkg-deb -I clickhouse-common-static_24.3.1.1_amd64.deb

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Nfpm_Package_Generation

Requires Environment

• Environment:ClickHouse_ClickHouse_Systemd_Runtime