Part 2: Installation & Quick Start

Time to stop talking theory and start running code. Installing ClickHouse is deceptively simple: you can spin it up in a Docker container in ten seconds. But running it in production without the kernel crashing or running out of file descriptors requires some configuration tweaks. Let’s get our hands dirty.

The Production Prerequisites (OS Tuning)

Before we download a single byte, we need to talk about system limits. ClickHouse reads and writes a lot of files. Every table partition is split into multiple column files. When queries execute, ClickHouse opens thousands of files concurrently.

If you try to run ClickHouse on a stock Linux machine, it will eventually crash with a painful Too many open files error.

To avoid this, you need to adjust your system limits. On Linux, open /etc/security/limits.conf and append the following lines:

clickhouse      soft    nofile      262144
clickhouse      hard    nofile      262144
clickhouse      soft    memlock     unlimited
clickhouse      hard    memlock     unlimited

One does not simply run ClickHouse in production with standard Linux default limits.

Additionally, disable Transparent Huge Pages (THP). While THP is great for some databases, it causes memory fragmentation and unpredictable latency spikes in ClickHouse. Run this to check:

cat /sys/kernel/mm/transparent_hugepage/enabled

If it says [always], disable it by adding transparent_hugepage=never to your kernel boot parameters or running:

echo 'never' | sudo tee /sys/kernel/mm/transparent_hugepage/enabled

For more OS tuning guidelines, refer to the official ClickHouse Linux OS Tuning Guide.

---

Method 1: Docker (The 10-Second Playground)

For local development or testing, Docker is the easiest way to roll. Run the following command in your terminal:

docker run -d \
  --name clickhouse-server \
  --ulimit nofile=262144:262144 \
  -p 8123:8123 \
  -p 9000:9000 \
  -p 9004:9004 \
  -v clickhouse-data:/var/lib/clickhouse \
  clickhouse/clickhouse-server

Deciphering the Flags:

• --ulimit nofile=262144:262144: Tells Docker to allow ClickHouse to open up to 262,144 files concurrently. Do not skip this!
• -p 8123:8123: The HTTP interface. This is what JDBC/ODBC drivers, DBeaver, and third-party UI tools use to talk to ClickHouse.
• -p 9000:9000: The native TCP interface. This is what the interactive command-line client (clickhouse-client) uses.
• -p 9004:9004: The gRPC interface for modern high-performance microservices.
• -v clickhouse-data:/var/lib/clickhouse: Standard Docker volume to ensure your databases don’t vanish when you stop the container.

---

Method 2: Native Installation (macOS & Linux)

For bare metal or virtual machines where you want maximum raw performance without container overhead, run the native installation scripts.

On macOS (using Homebrew)

brew install clickhouse

To start the ClickHouse service on macOS:

brew services start clickhouse

On Linux (Debian/Ubuntu)

Run the official ClickHouse installer script:

curl https://clickhouse.com/ | sh

This script detects your OS, downloads the appropriate binaries (including ARM64 support), and places them in your path. Then, run the server:

sudo ./clickhouse start

For deep native configurations and package managers, check the Official ClickHouse Installation Docs.

---

The Configuration Architecture: config.xml vs. users.xml

ClickHouse splits its configuration into two main files, usually located in /etc/clickhouse-server/:

1. config.xml (Server Settings): Controls ports, network interfaces, logging, directory paths, encryption, and clusters.
2. users.xml (User & Profile Settings): Controls user accounts, access permissions (RBAC), quotas, and memory query limits.

Pro Tip: Use config.d and users.d

Never edit config.xml or users.xml directly! When you upgrade ClickHouse, these files will be overwritten. Instead, place your custom settings in XML or YAML files inside /etc/clickhouse-server/config.d/ and /etc/clickhouse-server/users.d/.

Here is an example config file to allow connections from other machines. Save this as /etc/clickhouse-server/config.d/network.xml:

<clickhouse>
    <!-- Listen on all IPv4 interfaces -->
    <listen_host>0.0.0.0</listen_host>
</clickhouse>

---

Connecting & Running Your First Queries

Now that ClickHouse is running, let’s connect using the interactive native client:

docker exec -it clickhouse-server clickhouse-client

You should see a prompt like this:

ClickHouse client version 24.x.y.z.
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 24.x.y.z.

:) 

That :) is ClickHouse’s signature smiley prompt. If your query fails, it changes to a sad face :(, which is a neat little easter egg.

Let’s run a sanity check to verify the cluster is happy:

SELECT version();

┌─version()───┐
│ 24.3.2.46   │
└─────────────┘

Let’s check the built-in system tables to see how much memory the server has detected:

SELECT 
    formatReadableSize(total_physical_bytes) AS physical_memory,
    formatReadableSize(free_physical_bytes) AS free_memory
FROM system.asynchronous_metrics
LIMIT 1;

┌─physical_memory─┬─free_memory─┐
│ 16.00 GiB       │ 4.12 GiB    │
└─────────────────┴─────────────┘

Excellent. You have a fully configured ClickHouse server running. In the next part, we’ll dive into the heart of ClickHouse storage: the mighty MergeTree engine.