Implementation:ClickHouse ClickHouse Install Script
| Knowledge Sources | |
|---|---|
| Domains | Deployment |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Concrete tool for installing ClickHouse via the official quick-install script or DEB/RPM packages, including binary deployment, configuration placement, user creation, and systemd service registration.
Description
ClickHouse can be installed through two mechanisms:
Quick-install script: The one-liner `curl https://clickhouse.com/ | sh` downloads the ClickHouse binary for the current platform and architecture. This produces a standalone self-contained binary that can be run directly without further setup. The binary contains all ClickHouse tools multiplexed into a single executable.
DEB package installation: For production Linux systems using Debian/Ubuntu, ClickHouse provides `.deb` packages that must be installed in dependency order. The `clickhouse-server` package is defined by the nfpm configuration at `packages/clickhouse-server.yaml`, which specifies package metadata, file mappings, and a postinstall script. Key file mappings include:
- `/etc/clickhouse-server/config.xml` -- Server configuration (marked `config|noreplace` to preserve user edits on upgrade)
- `/etc/clickhouse-server/users.xml` -- User authentication and access control configuration
- `/lib/systemd/system/clickhouse-server.service` -- systemd service unit
- `/etc/init.d/clickhouse-server` -- SysV init script (legacy fallback)
- `/usr/bin/clickhouse-server` -- Symlink to the main `clickhouse` binary
The postinstall script (`packages/clickhouse-server.postinstall`) runs `clickhouse install` to create the `clickhouse` user and group, set up directories with proper ownership and permissions, then enables the systemd service or configures SysV init as appropriate.
The systemd service unit (`packages/clickhouse-server.service`) configures the server with `Type=notify` for proper readiness signaling, `Restart=always` with `RestartSec=30` for automatic recovery, and `LimitNOFILE=500000` for high-concurrency workloads.
Usage
Use the quick-install script for development and testing. Use DEB/RPM packages for production deployments requiring proper service management, system integration, and reproducible configuration.
Code Reference
Source Location
- Repository: ClickHouse
- File:
README.md(lines 16-20, quick install command) - File:
packages/clickhouse-server.yaml(lines 1-81, nfpm package definition) - File:
packages/clickhouse-server.postinstall(postinstall script) - File:
packages/clickhouse-server.service(systemd unit)
Signature
Quick-install script:
curl https://clickhouse.com/ | sh
DEB package installation:
dpkg -i clickhouse-common-static_*.deb clickhouse-server_*.deb clickhouse-client_*.deb
Postinstall invocation (from clickhouse-server.postinstall):
clickhouse install \
--user "${CLICKHOUSE_USER}" \
--group "${CLICKHOUSE_GROUP}" \
--pid-path "${CLICKHOUSE_PIDDIR}" \
--config-path "${CLICKHOUSE_CONFDIR}" \
--binary-path "${CLICKHOUSE_BINDIR}" \
--log-path "${CLICKHOUSE_LOGDIR}" \
--data-path "${CLICKHOUSE_DATADIR}"
systemd service ExecStart:
ExecStart=/usr/bin/clickhouse-server --config=/etc/clickhouse-server/config.xml --pid-file=%t/%p/%p.pid
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| DEB packages | Files | Yes (for package install) | Three `.deb` files: `clickhouse-common-static`, `clickhouse-server`, `clickhouse-client`. Must be installed in this order to satisfy dependencies. |
| Install script | URL | Yes (for quick install) | The URL `https://clickhouse.com/` serves the install script when piped to `sh`. |
| CLICKHOUSE_USER | Environment variable | No | User to run the server as. Defaults to `clickhouse`. |
| CLICKHOUSE_GROUP | Environment variable | No | Group for the server. Defaults to the value of `CLICKHOUSE_USER`. |
| CLICKHOUSE_CONFDIR | Environment variable | No | Configuration directory. Defaults to `/etc/clickhouse-server`. |
| CLICKHOUSE_DATADIR | Environment variable | No | Data directory. Defaults to `/var/lib/clickhouse`. |
| CLICKHOUSE_LOGDIR | Environment variable | No | Log directory. Defaults to `/var/log/clickhouse-server`. |
| CLICKHOUSE_BINDIR | Environment variable | No | Binary directory. Defaults to `/usr/bin`. |
Outputs
| Name | Type | Description |
|---|---|---|
| `/usr/bin/clickhouse` | Binary | The main ClickHouse multi-tool binary (from `clickhouse-common-static`) |
| `/usr/bin/clickhouse-server` | Symlink | Symlink to the main binary; dispatches to server entry point |
| `/usr/bin/clickhouse-client` | Symlink | Symlink to the main binary; dispatches to client entry point |
| `/usr/bin/clickhouse-keeper` | Symlink | Symlink to the main binary; dispatches to keeper entry point |
| `/etc/clickhouse-server/config.xml` | Config file | Default server configuration |
| `/etc/clickhouse-server/users.xml` | Config file | Default user authentication and access control configuration |
| `/lib/systemd/system/clickhouse-server.service` | Service unit | systemd service unit with `Type=notify`, `Restart=always`, `RestartSec=30`, `LimitNOFILE=500000`, capabilities: `CAP_NET_ADMIN CAP_IPC_LOCK CAP_SYS_NICE CAP_NET_BIND_SERVICE` |
| `clickhouse` user/group | System account | Dedicated non-root service account for running the ClickHouse server |
| `/var/lib/clickhouse` | Directory | Default data directory (mode 0700, owned by `clickhouse`) |
| `/var/log/clickhouse-server` | Directory | Default log directory (mode 0770, owned by `clickhouse`) |
Usage Examples
Quick install (development/testing):
# Download and run ClickHouse directly
curl https://clickhouse.com/ | sh
# Start the server
./clickhouse server
# In another terminal, connect with client
./clickhouse client
DEB package install (production):
# Install packages in dependency order
sudo dpkg -i clickhouse-common-static_24.8.1.1_amd64.deb
sudo dpkg -i clickhouse-server_24.8.1.1_amd64.deb
sudo dpkg -i clickhouse-client_24.8.1.1_amd64.deb
# Start the service
sudo systemctl start clickhouse-server
# Verify the service is running
sudo systemctl status clickhouse-server
# Enable the service to start on boot (usually done by postinstall)
sudo systemctl enable clickhouse-server
Using APT repository:
# Add ClickHouse repository
sudo apt-get install -y apt-transport-https ca-certificates
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754
echo "deb https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
# Install packages
sudo apt-get update
sudo apt-get install -y clickhouse-server clickhouse-client
# Start the service
sudo systemctl start clickhouse-server