Implementation:ClickHouse ClickHouse Nfpm Server Package

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

Overview

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

Description

The clickhouse-server package provides everything needed to run ClickHouse as a system service on Linux. It includes server and keeper configuration files, systemd service units, a SysV init script, symlinks for keeper-related binaries, and a post-install script that creates the clickhouse system user, sets up data and log directories, and enables the service.

This package depends on clickhouse-common-static at an exact version match and provides the clickhouse-keeper virtual package, meaning installing the server package also makes Keeper available. It recommends libcap2-bin for capability-based privilege management.

The YAML configuration uses format-specific overrides in the overrides section to express the dependency differently for DEB and RPM, since the two formats use different syntax for version constraints.

Usage

Use this package configuration when building the ClickHouse server package for distribution. The nfpm tool should be invoked from the packages/ directory after staging configuration files and symlink targets in the root/ subdirectory.

Code Reference

Source Location

• Repository: ClickHouse
• File: packages/clickhouse-server.yaml (lines 1--81)
• Related files:
  • packages/clickhouse-server.postinstall -- Post-install shell script
  • packages/clickhouse-server.service -- systemd unit file
  • packages/clickhouse-server.init -- SysV init script
  • packages/clickhouse-keeper.service -- Keeper systemd unit file

Signature

name: "clickhouse-server"
arch: "${DEB_ARCH}"
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-server-common
- clickhouse-server-base
provides:
- clickhouse-keeper
- clickhouse-server-common
recommends:
- libcap2-bin

overrides:
  deb:
    depends:
    - clickhouse-common-static (= ${CLICKHOUSE_VERSION_STRING})
  rpm:
    depends:
    - clickhouse-common-static = ${CLICKHOUSE_VERSION_STRING}

contents:
- src: root/etc/clickhouse-server/config.xml
  dst: /etc/clickhouse-server/config.xml
  type: config|noreplace
- src: root/etc/clickhouse-server/users.xml
  dst: /etc/clickhouse-server/users.xml
  type: config|noreplace
- src: clickhouse-server.init
  dst: /etc/init.d/clickhouse-server
- src: clickhouse-server.service
  dst: /lib/systemd/system/clickhouse-server.service
- src: root/usr/bin/clickhouse-server
  dst: /usr/bin/clickhouse-server
- src: root/etc/clickhouse-keeper/keeper_config.xml
  dst: /etc/clickhouse-keeper/keeper_config.xml
  type: config|noreplace
- src: clickhouse-keeper.service
  dst: /lib/systemd/system/clickhouse-keeper.service
- src: clickhouse
  dst: /usr/bin/clickhouse-keeper
  type: symlink
- src: clickhouse
  dst: /usr/bin/clickhouse-keeper-client
  type: symlink
- src: clickhouse
  dst: /usr/bin/clickhouse-keeper-converter
  type: symlink

scripts:
  postinstall: ./clickhouse-server.postinstall

API

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

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

I/O Contract

Inputs

Name	Type	Required	Description
root/etc/clickhouse-server/config.xml	XML config file	Yes	Default server configuration file
root/etc/clickhouse-server/users.xml	XML config file	Yes	Default users and access control configuration
root/etc/clickhouse-keeper/keeper_config.xml	XML config file	Yes	Default Keeper configuration
clickhouse-server.service	systemd unit	Yes	systemd service definition for ClickHouse server
clickhouse-server.init	Shell script	Yes	SysV init script for systems without systemd
clickhouse-keeper.service	systemd unit	Yes	systemd service definition for ClickHouse Keeper
root/usr/bin/clickhouse-server	Symlink/binary	Yes	Server entry point (typically a symlink to clickhouse)
clickhouse-server.postinstall	Shell script	Yes	Post-installation script for user creation, directory setup, and service enablement
${CLICKHOUSE_VERSION_STRING}	Environment variable	Yes	Version string for the package
${DEB_ARCH}	Environment variable	Yes	Target architecture

Outputs

Name	Type	Description
clickhouse-server_${VERSION}_${ARCH}.deb	Debian package	DEB package containing server configuration, services, and post-install automation
clickhouse-server-${VERSION}.${ARCH}.rpm	RPM package	RPM package with equivalent contents

Installed File Layout

The package installs the following files on the target system:

/etc/clickhouse-server/config.xml                      # Server config (noreplace)
/etc/clickhouse-server/users.xml                       # Users config (noreplace)
/etc/clickhouse-keeper/keeper_config.xml               # Keeper config (noreplace)
/etc/init.d/clickhouse-server                          # SysV init script
/lib/systemd/system/clickhouse-server.service          # Server systemd unit
/lib/systemd/system/clickhouse-keeper.service          # Keeper systemd unit
/usr/bin/clickhouse-server                             # Server binary/symlink
/usr/bin/clickhouse-keeper -> clickhouse               # Keeper symlink
/usr/bin/clickhouse-keeper-client -> clickhouse         # Keeper client symlink
/usr/bin/clickhouse-keeper-converter -> clickhouse      # Keeper converter symlink
/usr/share/doc/clickhouse-server/AUTHORS
/usr/share/doc/clickhouse-server/CHANGELOG.md
/usr/share/doc/clickhouse-server/LICENSE
/usr/share/doc/clickhouse-server/README.md

Post-Install Script Behavior

The post-install script (clickhouse-server.postinstall) performs the following actions:

1. Invokes clickhouse install to create the clickhouse user and group and set up server directories (/var/lib/clickhouse, /var/log/clickhouse-server, /var/run/clickhouse-server).
2. Detects the init system:
   • If systemd is available, removes legacy SysV init registration, reloads the systemd daemon, and enables the clickhouse-server service.
   • Otherwise, registers the SysV init script with update-rc.d using default runlevels.
3. Sets up Keeper directories (/var/lib/clickhouse, /var/log/clickhouse-keeper) with appropriate ownership and permissions.

Usage Examples

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

# Stage configuration files:
mkdir -p packages/root/etc/clickhouse-server
mkdir -p packages/root/etc/clickhouse-keeper
mkdir -p packages/root/usr/bin
cp programs/server/config.xml packages/root/etc/clickhouse-server/
cp programs/server/users.xml packages/root/etc/clickhouse-server/
cp programs/keeper/keeper_config.xml packages/root/etc/clickhouse-keeper/

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

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Server_Package_Configuration

Requires Environment

• Environment:ClickHouse_ClickHouse_Systemd_Runtime