Principle:ClickHouse ClickHouse Installation
| Knowledge Sources | |
|---|---|
| Domains | Deployment, Server_Administration |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Installing ClickHouse on production systems involves deploying prebuilt binaries via a quick-install script or native OS package managers, creating a dedicated service user, and registering the server as a managed system service.
Description
ClickHouse provides two primary installation paths for Linux, macOS, and FreeBSD systems:
Quick-install script: A single `curl https://clickhouse.com/ | sh` command downloads a self-contained ClickHouse binary. This path is ideal for quick evaluation, development environments, or systems where package manager integration is unnecessary. The downloaded binary contains all ClickHouse tools (server, client, local, keeper, and others) multiplexed behind a single executable that dispatches to the appropriate entry point based on the invoked name or the first positional argument.
DEB/RPM packages: For production deployments, ClickHouse distributes packages through its official APT and YUM repositories. The package set follows a layered dependency model:
- `clickhouse-common-static` -- Contains the core `clickhouse` binary and shared static libraries. This is the foundational package that all others depend on.
- `clickhouse-server` -- Depends on `clickhouse-common-static` at the exact same version. Installs default configuration files (`config.xml`, `users.xml`) to `/etc/clickhouse-server/`, the systemd service unit to `/lib/systemd/system/clickhouse-server.service`, and runs a postinstall script that creates the `clickhouse` user and group, sets up data directories at `/var/lib/clickhouse`, log directories at `/var/log/clickhouse-server`, and enables the systemd service.
- `clickhouse-client` -- Provides the `clickhouse-client` symlink and client-specific configuration.
The postinstall script (`clickhouse-server.postinstall`) invokes `clickhouse install` with arguments specifying the user, group, PID path, config path, binary path, log path, and data path. It then detects whether systemd is available and either enables the `clickhouse-server` systemd service or falls back to SysV init scripts via `update-rc.d`.
The systemd service unit runs ClickHouse as `Type=notify`, meaning the server signals readiness to systemd after full initialization rather than immediately on fork. This ensures that dependent services do not start until ClickHouse is actually ready to accept connections. The service runs under the `clickhouse` user/group, restarts automatically on failure with a 30-second delay, and is granted Linux capabilities `CAP_NET_ADMIN`, `CAP_IPC_LOCK`, `CAP_SYS_NICE`, and `CAP_NET_BIND_SERVICE` to allow binding to privileged ports, locking memory, and adjusting scheduling priorities without running as root.
Usage
Use the quick-install script for development, testing, or quick evaluation scenarios where you need ClickHouse running within seconds without permanent system integration. Use DEB/RPM packages for production deployments where you need proper service management, automatic restarts, log rotation integration, and reproducible deployments managed by configuration management tools such as Ansible, Puppet, or Chef.
Theoretical Basis
The installation architecture follows several important principles:
Single-binary multiplexing: ClickHouse compiles all its tools into a single static binary. The `main` function in `programs/main.cpp` maintains a dispatch table (`clickhouse_applications`) that maps subcommand names to entry-point functions. This design reduces disk footprint and simplifies distribution: a single binary plus a set of symlinks (e.g., `clickhouse-server` -> `clickhouse`) provides the full ClickHouse toolkit.
Layered packaging: The three-package structure (`common-static`, `server`, `client`) follows the principle of separation of concerns. The core binary is isolated so that updates to configuration or service definitions do not require re-downloading the large static binary. Configuration files are marked with `config|noreplace` in the package specification, ensuring that user customizations survive package upgrades.
systemd-notify integration: By using `Type=notify` rather than `Type=simple` or `Type=forking`, the service unit cooperates with systemd to accurately report when the server is ready for traffic. The `TimeoutStartSec=0` setting allows unlimited startup time, accommodating large deployments where table loading or recovery from the write-ahead log may take significant time.
Principle of least privilege: The server runs as a dedicated `clickhouse` user rather than root. Linux capabilities are granted selectively through `CapabilityBoundingSet` and `AmbientCapabilities` to provide only the specific privileges needed, rather than blanket root access.