Workflow:ClickHouse ClickHouse Server Deployment
| Knowledge Sources | |
|---|---|
| Domains | Deployment, Database_Operations, System_Administration |
| Last Updated | 2026-02-08 17:00 GMT |
Overview
End-to-end process for installing, configuring, and running a ClickHouse server instance from packages or the quick-install script.
Description
This workflow covers the operational deployment of ClickHouse as a database server. ClickHouse can be installed via the one-line curl installer, system packages (DEB/RPM), or by running the compiled binary directly. The monolithic binary architecture means the same `clickhouse` executable serves as server, client, and all utilities through symlink-based dispatch. Configuration is XML-based, with the server using `config.xml` for system settings and `users.xml` for access control. ClickHouse integrates a ZooKeeper-compatible Keeper component for coordination in clustered deployments. The server provides TCP (port 9000) and HTTP (port 8123) interfaces for client connections.
Usage
Execute this workflow when you need to set up a new ClickHouse server for analytics workloads, whether for development, staging, or production environments. This covers single-node deployments; clustered setups extend these steps with replication and coordination configuration.
Execution Steps
Step 1: Install ClickHouse
Install ClickHouse using the preferred method for your environment. The quickest option is the one-line curl installer (`curl https://clickhouse.com/ | sh`). For production environments, use the DEB or RPM packages which include systemd service files, proper user creation, and standard directory layout. The package hierarchy consists of `clickhouse-common-static` (base binary), `clickhouse-server` (server config and services), and `clickhouse-client` (interactive shell).
Key considerations:
- The curl installer downloads a self-contained binary
- DEB/RPM packages handle system user creation and directory setup automatically
- The `clickhouse-common-static` package is a dependency for all other packages
- The server package includes integrated Keeper configuration
Step 2: Configure the Server
Customize the server configuration in `config.xml` and user access in `users.xml`. Key configuration areas include listen addresses, data storage paths, logging, memory limits, and TLS/SSL settings for encrypted connections. The vendored Poco NetSSL_OpenSSL library provides the TLS implementation with support for protocol version selection, cipher suite configuration, and certificate management via the `SSLManager` singleton.
Key considerations:
- Default config listens on localhost only; change for remote access
- The `SSLManager` provides centralized SSL context management for both client and server sides
- Certificate handlers can be configured to accept, reject, or custom-handle invalid certificates
- Private key passphrase handlers support both console-based and configuration-file-based approaches
Step 3: Start the Server
Launch the ClickHouse server as a system service or foreground process. When installed via packages, use systemd (`systemctl start clickhouse-server`). For development, run the binary directly with the config file path. The server initializes OpenSSL, configures sanitizer options if built with them, disables `dlopen` for security, and begins accepting connections on configured ports.
Key considerations:
- Systemd service files are included in the server package
- Init.d scripts are provided for non-systemd systems
- The server binary is a symlink to the monolithic `clickhouse` binary
- The dispatch mechanism in `programs/main.cpp` routes to the server entry point based on the binary name
Step 4: Verify Server Health
Confirm the server is running and accepting connections. Use the ClickHouse client to execute a simple query, or use the HTTP interface for a health check. Verify that all configured interfaces (TCP, HTTP, and optionally HTTPS, MySQL, PostgreSQL wire protocols) are responding.
Key considerations:
- Quick check: `clickhouse-client -q "SELECT 1"`
- HTTP health check: `curl http://localhost:8123/ping`
- Check server logs for any startup errors or warnings
- Verify the integrated Keeper is running if needed for replication
Step 5: Connect with Client
Use the ClickHouse client to interact with the server. The client supports interactive mode with syntax highlighting, command history, and multi-line query editing. It can also execute queries non-interactively via the `-q` flag or by piping input.
Key considerations:
- Interactive mode: `clickhouse-client`
- Non-interactive: `clickhouse-client -q "SELECT version()"`
- The client binary is a symlink dispatched through the same monolithic binary
- Short alias `chc` is available for convenience