Principle:ClickHouse ClickHouse Server Package Configuration
| Knowledge Sources | |
|---|---|
| Domains | Packaging, Distribution |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Server package configuration is the practice of packaging a database server binary together with its systemd service definitions, init scripts, configuration files, and post-install scripts to enable turnkey deployment on Linux systems.
Description
A database server like ClickHouse requires more than just a binary to operate in production. It needs:
- Configuration files that define server behavior (listen addresses, storage paths, authentication).
- Init system integration (systemd unit files and/or SysV init scripts) so the server starts on boot, can be managed with standard tools, and restarts on failure.
- Post-install scripts that create system users, set directory ownership, configure permissions, and enable the service.
- Dependency declarations ensuring the base binary package is installed.
The server package configuration principle addresses how all these components are assembled into a single installable package that transforms a bare Linux system into a functional ClickHouse server with minimal manual intervention.
In the ClickHouse project, the server package also bundles ClickHouse Keeper -- a ZooKeeper-compatible coordination service -- because Keeper is built from the same binary and shares the server package's lifecycle. This means the server package provides symlinks for clickhouse-keeper, clickhouse-keeper-client, and clickhouse-keeper-converter, along with Keeper's own configuration and systemd service.
Usage
Server package configuration should be applied when:
- Building the
clickhouse-serverDEB or RPM package for distribution. - Deploying ClickHouse on Debian-based or Red Hat-based systems using package managers.
- Setting up ClickHouse Keeper as a coordination service, since Keeper is provided by the server package.
- Designing post-install automation that creates service users, sets permissions, and enables systemd services.
Theoretical Basis
Init System Integration
Modern Linux distributions use systemd as their init system, but some environments still rely on SysV init scripts. A well-designed server package includes both:
- systemd service file: Declaratively describes the service's startup command, dependencies, resource limits, restart policy, and security hardening options. The service is enabled with
systemctl enableduring post-install. - SysV init script: A shell script placed in
/etc/init.d/that responds tostart,stop,restart, andstatuscommands. Registered usingupdate-rc.dwith appropriate runlevel defaults.
The post-install script detects which init system is available and configures accordingly: if systemd is running, it removes any legacy init script registration and enables the systemd unit; otherwise, it falls back to SysV init.
Configuration File Handling
Configuration files require special treatment in packages because they may be modified by the operator after installation. The config|noreplace type in nfpm (equivalent to %config(noreplace) in RPM and conffile handling in DEB) ensures that:
- On fresh install, the default configuration is placed.
- On upgrade, if the operator has modified the file, the existing version is preserved and the new default is saved with a
.rpmnewor.dpkg-newsuffix. - On upgrade with unmodified config, the new version replaces the old one.
Post-Install Script Responsibilities
The server post-install script performs critical setup tasks:
- User/group creation: Creates a dedicated
clickhousesystem user and group with appropriate properties (no login shell, system account). - Directory setup: Creates and sets ownership on data directories (
/var/lib/clickhouse), log directories (/var/log/clickhouse-server), and PID directories (/var/run/clickhouse-server). - Permission hardening: Sets restrictive permissions on directories (e.g.,
0700for data,0770for logs). - Service enablement: Detects the init system and enables the ClickHouse server service for automatic startup.
- Keeper setup: Also creates directories and sets permissions for ClickHouse Keeper's configuration, data, and log paths.
Dependency Model
The server package depends on clickhouse-common-static at an exact version match. This strict version pinning ensures that the server binary and the configuration/service files are always in sync. The dependency is expressed differently per format:
- DEB:
clickhouse-common-static (= ${VERSION}) - RPM:
clickhouse-common-static = ${VERSION}
The server package also recommends libcap2-bin, which provides the setcap utility used to grant the ClickHouse binary the CAP_NET_ADMIN and other capabilities without running as root.