This post will walk you through the steps to install and run ClickHouse using Docker, ensuring you can leverage its powerful features efficiently.

Prerequisites

Before diving into the installation, ensure you have the following prerequisites:

1. Docker Desktop: Ensure your system meets the hardware requirements for Docker Desktop. This is essential for running Docker containers smoothly on your machine.
2. Docker Engine: Depending on your operating system (Windows, macOS, or Linux), follow the specific installation guides for Docker Engine.
3. Basic Knowledge: Familiarity with Docker, Docker Compose, and basic Linux commands will be beneficial.

Step-by-step installation guide

1. Pulling the ClickHouse image

To get started, you need to pull the official ClickHouse image from Docker Hub. This can be done using the Docker CLI:

docker pull clickhouse/clickhouse-server

This command fetches the ClickHouse image, which you can then use to create containers.

We recommend installing the last Long-Term Support (LTS) version. For example:

docker pull clickhouse/clickhouse-server:24.3.6

2. Running the ClickHouse container

Once the image is pulled, you can start a ClickHouse server using a basic Docker run command:

docker run -d --name clickhouse-server clickhouse/clickhouse-server

This command runs the ClickHouse server in a detached mode, naming the container clickhouse-server.

3. Configuring the container

To optimize the performance and ensure data persistence, you can adjust several parameters and mount the necessary volumes:

docker run -d --name clickhouse-server \
  --ulimit nofile=262144:262144 \
  --volume=$(pwd)/data:/var/lib/clickhouse \
  --volume=$(pwd)/logs:/var/log/clickhouse-server \
  --network=host \
	--cap-add=SYS_NICE \
  --cap-add=NET_ADMIN \
  --cap-add=IPC_LOCK \
  --cap-add=SYS_PTRACE \
  clickhouse/clickhouse-server:24.3.6

• ulimit: Sets the maximum number of open files.
• Volumes: Mounts directories for data and logs to ensure persistence.
• Network: Using -network=host can improve performance.
• (optional) You can enable additional ClickHouse features by setting certain Linux capabilities: SYS_PTRACE NET_ADMIN IPC_LOCK SYS_NICE

4. Using Docker Compose

For more complex setups, such as running a ClickHouse cluster, Docker Compose is a powerful tool. Create a docker-compose.yml file with the following content:

Add the following lines under the clickhouse-server service in your docker-compose.yml file to include the necessary capabilities:

version: '3'
services:
  clickhouse-server:
    image: clickhouse/clickhouse-server:24.3.6
    container_name: clickhouse-server
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    volumes:
      - ./data:/var/lib/clickhouse
      - ./logs:/var/log/clickhouse-server
    network_mode: host
    cap_add:
      - SYS_NICE
      - NET_ADMIN
      - IPC_LOCK
      - SYS_PTRACE

Run the following command to start the services defined in the docker-compose.yml file:

docker-compose up -d

This command will start the ClickHouse server as defined in the compose file.

5. Verifying the installation

After starting the container, verify the installation by logging into the ClickHouse client:

docker exec -it clickhouse-server clickhouse-client

You can then run basic SQL queries to ensure everything is set up correctly:

SELECT * FROM system.databases;

This query lists all the databases available in ClickHouse.

Configuration and optimization

Configuration files

ClickHouse uses several configuration files to manage its settings:

config.xml: Primary configuration file for database behavior, storage engines, and query processing. Here is an example config.xml file:

<clickhouse>
    <profiles>
        <default>
            <max_query_size>150000</max_query_size>
        </default>
    </profiles>
</clickhouse>

users.xml: Manages user access and permissions. Here is an example users.xml file:

<clickhouse>
    <users>
        <admin>
            <password_sha256_hex>8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918</password_sha256_hex>
            <access_management>1</access_management>
        </admin>
    </users>
</clickhouse>

To start a ClickHouse container using custom config.xml and users.xml configuration files, you need to mount these files into the container. Follow these steps:

1. Place your custom config.xml and users.xml files in a directory on your host machine, for example, ./config.

2. Use the following Docker run command to start the ClickHouse server with these custom configuration files:

docker run -d --name clickhouse-server \
  --ulimit nofile=262144:262144 \
  --volume=$(pwd)/data:/var/lib/clickhouse \
  --volume=$(pwd)/logs:/var/log/clickhouse-server \
  --volume=$(pwd)/config/config.xml:/etc/clickhouse-server/config.xml \
  --volume=$(pwd)/config/users.xml:/etc/clickhouse-server/users.xml \
  --network=host \
  --cap-add=SYS_NICE \
  --cap-add=NET_ADMIN \
  --cap-add=IPC_LOCK \
  --cap-add=SYS_PTRACE \
  clickhouse/clickhouse-server:24.3.6

In this command:

• -volume=$(pwd)/config/config.xml:/etc/clickhouse-server/config.xml: Mounts your custom config.xml file into the container.
• -volume=$(pwd)/config/users.xml:/etc/clickhouse-server/users.xml: Mounts your custom users.xml file into the container.

Here is the equivalent docker-compose.yml file.

version: '3'
services:
  clickhouse-server:
    image: clickhouse/clickhouse-server:24.3.6
    container_name: clickhouse-server
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    volumes:
      - ./data:/var/lib/clickhouse
      - ./logs:/var/log/clickhouse-server
      - ./config/config.xml:/etc/clickhouse-server/config.xml
      - ./config/users.xml:/etc/clickhouse-server/users.xml
    network_mode: host
    cap_add:
      - SYS_NICE
      - NET_ADMIN
      - IPC_LOCK
      - SYS_PTRACE

Again, you can test it with the following command:

docker exec -it clickhouse-server clickhouse-client

Now you have a ClickHouse running using Docker 🎉🎉.

Conclusion

By following the step-by-step instructions in this post, you should be able to install and run ClickHouse using Docker efficiently. Whether you are setting up a single server or a complex cluster, Docker provides a flexible and powerful environment to leverage ClickHouse's capabilities.

For a high-availability production-grade ClickHouse, you can get started in minutes with Propel's Serverless ClickHouse today and receive $15 in monthly credits forever. At any point, upgrade to pay-as-you-go, or contact us to learn more about our volume-based discounts. Visit our pricing page for details.

‍