Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 35 ยท Architecture and Setup

Install and Run ClickHouse

Install and start ClickHouse with the official quick-install script, Linux packages, Docker or ClickHouse Cloud, check it works, and know the default ports and folders.

You can run ClickHouse in minutes on a laptop and later move the same SQL to a cluster or to the managed cloud service. This lesson covers the common ways to install it, how to check that the server is alive, and where its files and ports live. ClickHouse itself does not run in this site's browser runner, so every command here is read-only: copy it to your own machine. Checking versions and exact flags against the official documentation is wise, because installation details change between releases.

Commands that pipe a downloaded script into a shell run code from the internet. Read the script first, and prefer your operating system's package manager or the official Docker image when you can.

Choose how to run it

Option Best for Notes
Quick install binary Learning, trying features One file, no root needed
Linux packages (apt, yum) Servers System service, upgrades with the package manager
Docker image Development, CI, reproducible setups Easy to throw away
ClickHouse Cloud Production without operating it Managed, scales storage and compute
clickhouse-local Querying files with no server Same engine, command line only

ClickHouse runs natively on Linux (x86-64 and ARM). On macOS the single binary works for development. On Windows use WSL2 or Docker.

Option 1: the single binary

The project offers a download script that fetches one executable named clickhouse. That same binary acts as the server, the client and the local tool depending on the argument.

Terminal
curl https://clickhouse.com/ | sh      # downloads ./clickhouse
./clickhouse server                    # start a server in this folder (terminal 1)
./clickhouse client                    # connect to it (terminal 2)

Data is created in the current folder, which is ideal for experiments you can delete afterwards.

Option 2: Linux packages

On Debian or Ubuntu you add the project's apt repository, then install two packages:

Terminal
sudo apt-get install -y clickhouse-server clickhouse-client
sudo systemctl start clickhouse-server
sudo systemctl enable clickhouse-server
clickhouse-client

The installer asks for a password for the default user. On a server you also open firewall ports only for the networks that need them, and you never expose ClickHouse's native port to the internet without authentication and TLS.

Option 3: Docker

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

docker exec -it ch clickhouse-client

The named volume keeps data when the container is replaced. The raised file-descriptor limit avoids "too many open files" errors on busy servers. For a login, pass -e CLICKHOUSE_USER=... -e CLICKHOUSE_PASSWORD=... (choose your own values and keep them out of source control).

A small Docker Compose file keeps this repeatable:

YAML
services:
  clickhouse:
    image: clickhouse/clickhouse-server
    ports: ["8123:8123", "9000:9000"]
    volumes: ["ch_data:/var/lib/clickhouse"]
    ulimits:
      nofile: { soft: 262144, hard: 262144 }
volumes:
  ch_data:

Option 4: ClickHouse Cloud

ClickHouse Cloud is the managed service. You create a service in the web console, copy the host and credentials, and connect with the same client or with a driver over TLS. It handles replication, backups and scaling for you, which is why it is a common production choice for small teams. Prices and plans change, so look at the current page rather than relying on a tutorial.

Check that it works

SQL
SELECT version();
SELECT 1;
SELECT currentDatabase(), currentUser();
SELECT uptime();

From a terminal, the HTTP interface answers a ping without any client:

Terminal
curl http://localhost:8123/ping        # prints: Ok.
curl 'http://localhost:8123/?query=SELECT%20version()'

Default ports and folders

What Default
HTTP interface 8123
HTTPS interface 8443
Native TCP (clickhouse-client, drivers) 9000
Native TCP with TLS 9440
Replica-to-replica traffic 9009
ClickHouse Keeper 9181 (client port, commonly)
Data /var/lib/clickhouse/
Configuration /etc/clickhouse-server/ (config.xml, config.d/, users.xml, users.d/)
Logs /var/log/clickhouse-server/

You rarely edit config.xml itself. Instead you drop override files into config.d/ and users.d/, which survive upgrades. See settings, users and config.

Your first session

Once connected, try a sequence like this (read-only here):

SQL
CREATE DATABASE IF NOT EXISTS demo;
USE demo;

CREATE TABLE hello
(
    id UInt32,
    msg String
)
ENGINE = MergeTree ORDER BY id;

INSERT INTO hello VALUES (1, 'hello'), (2, 'ClickHouse');
SELECT * FROM hello ORDER BY id;

Practice the first session with a stand-in

SQLite is not ClickHouse, but you can rehearse the same statements. The stand-in omits ENGINE and ORDER BY.

SQL Stand-in: the first session (SQLite)

Press Run (or Ctrl + Enter) to see the result here.

SQL Stand-in: a health-check style query

Press Run (or Ctrl + Enter) to see the result here.

Upgrades and versions

ClickHouse releases monthly stable versions and a few long-term support (LTS) versions per year. Production systems often follow an LTS line. Upgrade replicas one at a time, read the changelog for "backward incompatible changes" first, and test queries on a staging copy. SELECT version() tells you which release a server runs, which also tells you which features (like newer JSON handling) are available.

Common beginner mistakes

  • Exposing port 9000 or 8123 to the internet with the default, passwordless user.
  • Running without a persistent volume in Docker and losing data when the container is removed.
  • Forgetting the file-descriptor limit on busy servers.
  • Following a tutorial for an old version without checking the docs for yours.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which port does the ClickHouse HTTP interface use by default?

    8123 is HTTP; 9000 is the native TCP protocol used by clickhouse-client.
  2. 2. How do you keep data when a ClickHouse Docker container is replaced?

    Container filesystems are temporary; mount a volume at the data directory.
  3. 3. Where should you put your configuration overrides?

    Override files in config.d and users.d are merged in and survive package upgrades.
  4. 4. Which tool lets you run ClickHouse SQL on files without a server?

    clickhouse-local is the engine as a command-line tool for local files.

Summary

  • You can run ClickHouse as a single binary, from Linux packages, in Docker or as ClickHouse Cloud.
  • HTTP is on 8123 and the native protocol on 9000; data lives in /var/lib/clickhouse.
  • Put configuration in config.d/ and users.d/, not in config.xml.
  • Never expose the default user to the internet; use volumes in Docker.
  • ClickHouse code is read-only on this site; try the commands on your own machine.

Next: Clients, HTTP and formats