ClickHouse Local Docker: Quick Setup Guide

Hey everyone! Today, we’re diving into how to get ClickHouse up and running locally using Docker. If you’re looking to explore ClickHouse without the hassle of a full-blown installation, or if you need a consistent environment for development and testing, Docker is your best friend. This guide will walk you through the process step-by-step, making it super easy to get started. Let’s jump right in!

Why Use Docker for ClickHouse?

Before we get our hands dirty, let’s quickly chat about why using Docker is such a great idea for ClickHouse.

• Isolation: Docker containers provide isolated environments. This means ClickHouse runs in its own little bubble, without interfering with your system’s other applications and libraries. No more dependency conflicts!
• Consistency: Docker ensures that your ClickHouse environment is consistent across different machines. Whether you’re on your local machine, a staging server, or a production environment, Docker guarantees that ClickHouse behaves the same way everywhere.
• Ease of Use: Docker simplifies the setup process. Instead of manually installing and configuring ClickHouse, you can get it running with just a few simple commands. This saves you time and effort, especially when setting up multiple instances.
• Reproducibility: Docker allows you to create reproducible environments. You can define your ClickHouse configuration in a Dockerfile and share it with your team. This ensures that everyone is working with the same setup, reducing the risk of errors and inconsistencies.

By leveraging Docker, you can focus on what really matters: exploring ClickHouse’s powerful features and building amazing data applications. Plus, if you mess something up, you can just tear down the container and start fresh. It’s like having a reset button for your database!

Prerequisites

Before we start, make sure you have the following installed on your system:

• Docker: If you don’t have Docker installed, head over to the official Docker website and follow the installation instructions for your operating system.
• Docker Compose (Optional): While not strictly required, Docker Compose makes managing multi-container applications much easier. If you plan to run ClickHouse alongside other services, consider installing Docker Compose as well. You can find the installation instructions here .

Once you have these prerequisites in place, you’re ready to move on to the next step.

Step 1: Pull the ClickHouse Docker Image

The first thing we need to do is pull the official ClickHouse Docker image from Docker Hub. This image contains everything you need to run ClickHouse in a container. Open your terminal and run the following command:

docker pull clickhouse/clickhouse-server

This command downloads the latest version of the ClickHouse server image to your local machine. If you want to use a specific version of ClickHouse, you can specify it using a tag. For example, to pull version 23.3 , you would run:

docker pull clickhouse/clickhouse-server:23.3

Once the image is downloaded, you can verify it by running:

docker images

This command lists all the Docker images on your system. You should see the clickhouse/clickhouse-server image in the list.

Step 2: Run the ClickHouse Container

Now that we have the ClickHouse image, we can create and run a container. Run the following command in your terminal:

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

Let’s break down this command:

• -d : Runs the container in detached mode, meaning it runs in the background.
• --name clickhouse-server : Assigns the name clickhouse-server to the container. This makes it easier to refer to the container in subsequent commands.
• -p 8123:8123 : Maps port 8123 on the host to port 8123 on the container. This is the port used for the ClickHouse HTTP interface.
• -p 9000:9000 : Maps port 9000 on the host to port 9000 on the container. This is the port used for the ClickHouse native interface.
• clickhouse/clickhouse-server : Specifies the image to use for the container.

After running this command, Docker will create and start a ClickHouse container. You can check the status of the container by running:

docker ps

This command lists all the running containers on your system. You should see the clickhouse-server container in the list, along with its status and port mappings.

Step 3: Connect to ClickHouse

With the ClickHouse container up and running, you can now connect to it using various clients. Let’s explore a couple of options.

Using the ClickHouse Client

ClickHouse provides a command-line client that you can use to interact with the server. To connect to ClickHouse using the client, you first need to enter the container. Run the following command:

docker exec -it clickhouse-server clickhouse-client

This command opens a terminal session inside the clickhouse-server container and starts the clickhouse-client . You should see a prompt like this:

ClickHouse client version: 23.3.2.14 (official build)
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 23.3.2 or later.

host:.

Now you can execute SQL queries against the ClickHouse server. For example, to create a simple table, run:

CREATE TABLE IF NOT EXISTS my_table (
    id UInt32,
    name String
) ENGINE = Memory;

To insert some data into the table, run:

INSERT INTO my_table (id, name) VALUES
(1, 'Alice'),
(2, 'Bob'),
(3, 'Charlie');

And to query the data, run:

SELECT * FROM my_table;

You should see the data you just inserted.

Using the HTTP Interface

ClickHouse also provides an HTTP interface that you can use to interact with the server. To execute a query using the HTTP interface, you can use curl or any other HTTP client. For example, to execute the same SELECT query as above, you can run:

curl 'http://localhost:8123/?query=SELECT * FROM my_table'

This command sends an HTTP request to the ClickHouse server, executes the query, and returns the results in the response body. You should see the data in a tab-separated format.

Step 4: Using Docker Compose (Optional)

If you want to run ClickHouse alongside other services, such as a web application or a data pipeline, Docker Compose can be a great tool. Create a file named docker-compose.yml in your project directory and add the following content:

version: '3.8'
services:
  clickhouse:
    image: clickhouse/clickhouse-server
    ports:
      - "8123:8123"
      - "9000:9000"
    volumes:
      - clickhouse_data:/var/lib/clickhouse

volumes:
  clickhouse_data:

This file defines a single service named clickhouse that uses the clickhouse/clickhouse-server image. It also maps the necessary ports and defines a volume for persistent storage.

To start the ClickHouse service, run the following command in your project directory:

docker-compose up -d

This command creates and starts the ClickHouse container in detached mode. You can check the status of the container by running:

docker-compose ps

To stop the ClickHouse service, run:

docker-compose down

Using Docker Compose simplifies the management of multi-container applications and makes it easier to define and share your ClickHouse environment.

Step 5: Configuring ClickHouse (Optional)

ClickHouse can be configured using configuration files. The default configuration file is located at /etc/clickhouse-server/config.xml inside the container. To customize the ClickHouse configuration, you can mount a local directory containing your configuration files to the container. For example, create a directory named clickhouse-config in your project directory and add a file named config.xml with your custom configuration. Then, modify the docker-compose.yml file to mount the directory:

version: '3.8'
services:
  clickhouse:
    image: clickhouse/clickhouse-server
    ports:
      - "8123:8123"
      - "9000:9000"
    volumes:
      - ./clickhouse-config:/etc/clickhouse-server
      - clickhouse_data:/var/lib/clickhouse

volumes:
  clickhouse_data:

Now, when you start the ClickHouse container, it will use your custom configuration file.

Common Issues and Solutions

Port Conflicts

If you encounter port conflicts when running the ClickHouse container, it means that another application is already using port 8123 or 9000 on your host machine. To resolve this issue, you can either stop the other application or change the port mappings in the docker run command or the docker-compose.yml file. For example, to map port 8124 on the host to port 8123 on the container, you would use -p 8124:8123 .

Data Persistence

By default, data stored in the ClickHouse container is not persisted when the container is stopped or removed. To persist data, you need to use a Docker volume. In the docker-compose.yml file, we defined a volume named clickhouse_data and mounted it to the /var/lib/clickhouse directory inside the container. This ensures that data is stored on the host machine and is not lost when the container is stopped or removed.

Memory Limits

ClickHouse can be memory-intensive, especially when processing large datasets. If you encounter memory-related issues, you can increase the memory limit for the container. You can do this by adding the --memory flag to the docker run command or by specifying the mem_limit option in the docker-compose.yml file. For example, to limit the container to 4GB of memory, you would use --memory 4g .

Conclusion

And there you have it! You’ve successfully set up ClickHouse locally using Docker. This setup provides a clean, consistent, and isolated environment for exploring ClickHouse’s features. Whether you’re developing a new data application or just experimenting with ClickHouse, Docker makes the process much easier and more efficient. Remember to explore the official ClickHouse documentation for more advanced configuration options and features. Happy querying, folks!