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.

‍