How to Install ClickHouse Using Docker

April 25, 2025

ClickHouse is a fast, open-source columnar database designed for analytics. Thanks to its official Docker images, you can quickly spin it up locally or in CI environments without fuss. Let’s walk through a friendly step-by-step setup!

1. Pick the Official Docker Image

Use ClickHouse's official Docker image for best results:

docker pull clickhouse/clickhouse-server:latest

This image includes the stable, up-to-date version maintained by the ClickHouse team.

2. Run a Basic ClickHouse Container

Start your container with minimal configuration:

docker run -d \
  --name clickhouse-server \
  -p 9000:9000 \
  -p 8123:8123 \
  clickhouse/clickhouse-server:latest

Port 9000 is for the native client.
Port 8123 lets you query via HTTP.
By default, ClickHouse runs without a password and allows only local connections.

3. Add Persistent Storage

To preserve data beyond container restarts, mount local folders:

docker run -d \
  --name clickhouse-server \
  -p 9000:9000 -p 8123:8123 \
  -v ~/clickhouse/data:/var/lib/clickhouse \
  -v ~/clickhouse/logs:/var/log/clickhouse-server \
  clickhouse/clickhouse-server:latest

Now your database and logs survive container restarts.

4. Try Docker Compose

A docker-compose.yml setup adds organization:

version: '3'
services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    container_name: clickhouse
    ports:
      - "9000:9000"
      - "8123:8123"
    volumes:
      - ./data:/var/lib/clickhouse
      - ./logs:/var/log/clickhouse-server

Launch it with:

docker-compose up -d

Your data and logs will live under ./data and ./logs.

5. Connect Using the Native Client

Access your container’s shell to use the ClickHouse client:

docker exec -it clickhouse-server clickhouse-client

Then query the server, for example:

SHOW DATABASES;

You should see default databases like default, system, and more

6. Optional Configuration & Scripts

Want to customize or initialize on startup? Drop .xml, .sql, or .sh files into:

/docker-entrypoint-initdb.d/

The container will automatically process them before starting hub.docker.com. You can include queries to create tables, tweak users, or apply config overrides.

7. Tune for Production

For more serious setups:

Use --network=host for performance
Increase file descriptors with --ulimit nofile=262144:262144.
Mount config overrides in config.d/ or users.d/ folders.
Run with added Linux capabilities (CAP_SYS_NICE, CAP_IPC_LOCK) if needed for advanced features
Quick: Local testing in minutes.
Durable: Data lives on your host.
Flexible: Use Docker Compose or scripts for advanced setups.
Production-ready: Easy upgrades, configs, and scaling options.
Pull the official clickhouse/clickhouse-server image.
Run it with ports 9000 and 8123 exposed.
Mount volumes for data and logs.
Connect via clickhouse-client.
Customize via entrypoint scripts and config files.
Scale it up with ulimits, host networking, and custom setups.

With Docker, ClickHouse becomes effortless to install and manage. It’s perfect for local development and a great stepping stone to production architectures.