Environment:ClickHouse ClickHouse Systemd Runtime
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Deployment |
| Last Updated | 2026-02-08 18:00 GMT |
Overview
Linux systemd runtime environment for deploying ClickHouse as a managed service with automatic startup, resource limits, and process management via DEB/RPM packages.
Description
ClickHouse server packages (`clickhouse-server`) include systemd service unit files that manage the ClickHouse process lifecycle. The server package installs configuration files to `/etc/clickhouse-server/`, creates a dedicated `clickhouse` user and group, and sets up systemd service management. The package system uses nfpm for declarative DEB/RPM generation, with post-install scripts that configure the service.
Usage
Use this environment for any Server Deployment workflow on production Linux systems. It is the standard deployment target for DEB/RPM package installation. Systemd manages automatic startup on boot, graceful shutdown, and process restarts.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux with systemd | Ubuntu 20.04+, Debian 11+, CentOS 7+, RHEL 7+, or similar |
| Init System | systemd | Required for service management; non-systemd init supported via manual startup |
| User | `clickhouse` user/group | Created by package post-install scripts |
| Network | TCP ports 8123, 9000 | HTTP (8123) and native TCP (9000) ports; configurable in `config.xml` |
| Disk | Varies by data volume | Default data path: `/var/lib/clickhouse/`; log path: `/var/log/clickhouse-server/` |
Dependencies
System Packages
- `clickhouse-common-static` (core binary)
- `clickhouse-server` (server configuration, systemd unit, scripts)
- `clickhouse-client` (optional, for client tools)
Configuration Files
- `/etc/clickhouse-server/config.xml` (main server configuration)
- `/etc/clickhouse-server/users.xml` (user authentication and settings)
- `/etc/clickhouse-server/config.d/` (configuration overrides directory)
Credentials
- System user `clickhouse` with appropriate file permissions on data and log directories
- Optional TLS certificates (see OpenSSL_Runtime environment)
- Optional authentication credentials in `users.xml` or LDAP configuration
Quick Install
# Quick install via official script
curl https://clickhouse.com/ | sh
# Or via APT repository
sudo apt-get install -y clickhouse-server clickhouse-client
# Start the service
sudo systemctl start clickhouse-server
# Verify
clickhouse-client -q "SELECT 1"
Code Evidence
Server package nfpm definition from `packages/clickhouse-server.yaml:1-15`:
name: "clickhouse-server"
arch: "${DEB_ARCH}"
platform: "linux"
version: "${CLICKHOUSE_VERSION_STRING}"
vendor: "ClickHouse Inc."
homepage: "https://clickhouse.com"
license: "Apache-2.0"
section: "database"
priority: "optional"
Service configuration files from `packages/clickhouse-server.yaml:24-45`:
contents:
- src: root/etc/clickhouse-server/config.xml
dst: /etc/clickhouse-server/config.xml
type: config
- src: root/etc/clickhouse-server/users.xml
dst: /etc/clickhouse-server/users.xml
type: config
Install script reference from `README.md:16-20`:
curl https://clickhouse.com/ | sh
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `systemctl start clickhouse-server` fails | Permission issues on data/log directories | Ensure `/var/lib/clickhouse/` and `/var/log/clickhouse-server/` are owned by `clickhouse:clickhouse` |
| `Address already in use` | Ports 8123/9000 already occupied | Check for running instances: `pgrep -f clickhouse`; change ports in `config.xml` |
| Package dependency errors | Missing `clickhouse-common-static` | Install base package first: `apt install clickhouse-common-static` |
Compatibility Notes
- Non-systemd systems: ClickHouse can be started manually with `clickhouse-server --config-file /etc/clickhouse-server/config.xml --daemon`.
- Package formats: Both DEB (Debian/Ubuntu) and RPM (CentOS/RHEL) packages are generated from the same nfpm YAML definitions.
- Configuration overrides: Use files in `/etc/clickhouse-server/config.d/` for customization instead of modifying `config.xml` directly.
- macOS deployment: Not packaged for macOS; use the binary directly or build from source.