Workflow:ClickHouse ClickHouse Packaging For Distribution
| Knowledge Sources | |
|---|---|
| Domains | Packaging, DevOps, Linux_Distribution |
| Last Updated | 2026-02-08 17:00 GMT |
Overview
End-to-end process for creating distributable DEB and RPM packages from a compiled ClickHouse binary using nfpm package definitions.
Description
This workflow covers the packaging of ClickHouse into standard Linux distribution packages (DEB for Debian/Ubuntu, RPM for RHEL/CentOS). ClickHouse's packaging system uses nfpm YAML definitions to declare package contents, dependencies, and installation scripts. The packages follow a modular structure: a common static package containing the core binary, a server package with configuration and service files, a client package with the interactive shell, a keeper package for standalone ZooKeeper replacement, and debug symbol packages. Each package creates symlinks to the monolithic `clickhouse` binary for the relevant sub-application names.
Usage
Execute this workflow after successfully building ClickHouse from source when you need to create installable packages for deployment to production servers, distribution through package repositories, or sharing with users who prefer standard system package management.
Execution Steps
Step 1: Build the ClickHouse Binary
Compile ClickHouse in Release mode to produce an optimized binary suitable for distribution. The build should include all standard components (server, client, keeper) and use static linking for maximum portability across Linux distributions.
Key considerations:
- Use Release or RelWithDebInfo build type for production packages
- Ensure all desired components are enabled (`ENABLE_CLICKHOUSE_ALL=ON`)
- Static linking is the default and preferred mode for distribution
Step 2: Prepare Package Artifacts
Collect the compiled binary, configuration files, service definitions, and installation scripts into the expected directory structure. The packaging system expects specific paths for the binary, config files (`config.xml`, `users.xml`), systemd units, and init.d scripts.
Key considerations:
- Debug symbols should be split into a separate file for the debug package
- The binary must support the busybox-style dispatch for all symlink names
- Configuration files include both server and keeper defaults
Step 3: Generate Common Static Package
Build the `clickhouse-common-static` package using its nfpm YAML definition. This package contains the core `clickhouse` binary and is a dependency for all other packages. It provides the foundation that other packages build upon by creating symlinks.
Key considerations:
- This is the base package required by all other ClickHouse packages
- Contains only the monolithic binary, no configuration or service files
- Pre-build scripts may be used for environment preparation
Step 4: Generate Server Package
Build the `clickhouse-server` package containing the server symlink, configuration files, systemd and init.d service units, and bundled Keeper components. This package depends on `clickhouse-common-static` and provides the `clickhouse-keeper` capability. A postinstall script handles initial setup.
Key considerations:
- Includes both server and integrated Keeper configuration
- Creates the `clickhouse-server` and `clickhouse-keeper` symlinks
- Provides systemd service files for automatic startup
- The postinstall script creates system users and directories
Step 5: Generate Client Package
Build the `clickhouse-client` package containing the client symlink, bash completion scripts, and client-specific configuration. This package provides the interactive SQL shell for connecting to ClickHouse servers.
Key considerations:
- Depends on `clickhouse-common-static`
- Includes bash completion for improved command-line experience
- The client binary is accessed via the `clickhouse-client` symlink
Step 6: Generate Debug Symbols Package
Build the `clickhouse-common-static-dbg` and `clickhouse-keeper-dbg` packages containing stripped debug symbols. These packages enable detailed crash analysis and profiling on deployed systems without bloating the main packages.
Key considerations:
- Separate packages keep the main binary small
- Debug symbols are essential for analyzing core dumps in production
- Both server and keeper debug packages are available
Step 7: Validate Packages
Verify that all generated packages can be installed cleanly, that dependencies resolve correctly, that services start properly, and that the symlink dispatch works for all sub-applications.
Key considerations:
- Test installation on a clean system to verify dependency completeness
- Verify that systemd service units load and start correctly
- Check that all symlinks resolve to the correct binary