ClickHouse On Docker: Quick Installation Guide

Oct 23, 2025 by Jhon Lennon 47 views

Hey guys! Ever wanted to dive into the world of ClickHouse but felt intimidated by the installation process? Well, fear no more! This guide will walk you through installing ClickHouse using Docker, making it super easy to get up and running. Docker simplifies the deployment and management of applications, and ClickHouse is no exception. So, let's get started and unleash the power of ClickHouse with minimal fuss!

Why Docker for ClickHouse?

Before we jump into the installation, let's quickly discuss why using Docker is a fantastic idea for ClickHouse.

Isolation: Docker containers provide an isolated environment for ClickHouse, ensuring that it doesn't interfere with other applications on your system. This is especially useful if you're running multiple databases or services on the same machine.
Consistency: Docker ensures that ClickHouse runs consistently across different environments, whether it's your development machine, a testing server, or a production cluster. No more "it works on my machine" issues!
Simplicity: Docker simplifies the installation and configuration process, allowing you to get ClickHouse up and running with just a few commands. It also makes it easy to manage and upgrade ClickHouse in the future.
Reproducibility: Docker allows you to create reproducible environments, making it easy to share your ClickHouse setup with others. You can simply share your Dockerfile or Docker Compose file, and others can recreate your environment with ease.
Portability: Docker containers are portable, meaning you can easily move them between different machines or cloud providers. This makes it easy to scale your ClickHouse deployment as your needs grow.

Using Docker for ClickHouse is a no-brainer, especially if you value simplicity, consistency, and portability. It's a great way to get started with ClickHouse and explore its capabilities without the hassle of manual installation and configuration. Plus, it keeps your system clean and organized, which is always a good thing!

Prerequisites

Before we begin, make sure you have the following prerequisites in place:

Docker: Ensure that Docker is installed on your system. If you haven't already, download and install it from the official Docker website (https://www.docker.com/). Docker is available for Windows, macOS, and Linux, so choose the appropriate version for your operating system.
Docker Compose (Optional): While not strictly required, Docker Compose makes it easier to manage multi-container applications. If you plan to run ClickHouse with additional services (like ZooKeeper), Docker Compose is highly recommended. You can download and install it from the Docker website as well.
Basic Terminal Knowledge: You'll need to be comfortable using the command line or terminal to execute Docker commands. This includes navigating directories, running commands, and understanding basic Docker concepts.

Once you have these prerequisites in place, you're ready to start installing ClickHouse with Docker. Let's move on to the next section and see how it's done!

Step-by-Step Installation

Alright, let's dive into the actual installation process. We'll cover two methods: using the Docker CLI directly and using Docker Compose. Both methods are straightforward, but Docker Compose is generally preferred for more complex setups.

Method 1: Using Docker CLI

This method involves using the docker run command to create and start a ClickHouse container.

Pull the ClickHouse Image:

First, you need to pull the official ClickHouse image from Docker Hub. 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. The download time may vary depending on your internet connection speed.
Run the ClickHouse Container:

Once the image is downloaded, you can create and start a ClickHouse container using the following command:
```
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 (in the background).
- --name clickhouse-server: Assigns the name "clickhouse-server" to the container.
- -p 8123:8123: Maps port 8123 on the host machine to port 8123 on the container (HTTP interface).
- -p 9000:9000: Maps port 9000 on the host machine to port 9000 on the container (native interface).
- clickhouse/clickhouse-server: Specifies the image to use for the container.
Verify the Installation:

To verify that ClickHouse is running correctly, you can use the docker ps command to list the running containers:
```
docker ps
```
You should see a container named "clickhouse-server" in the output. You can also use the ClickHouse client to connect to the server:
```
docker exec -it clickhouse-server clickhouse-client
```
This command executes the clickhouse-client command inside the container, allowing you to interact with the ClickHouse server. If everything is working correctly, you should see the ClickHouse command-line interface.

Method 2: Using Docker Compose

This method uses a docker-compose.yml file to define and manage the ClickHouse container. This is a more organized approach, especially if you have multiple containers to manage.

Create a docker-compose.yml File:

Create a new file named docker-compose.yml in a directory of your choice. Open the file in a text editor and add the following content:
```
version: '3.7'
services:
  clickhouse-server:
    image: clickhouse/clickhouse-server
    ports:
      - "8123:8123"
      - "9000:9000"
    volumes:
      - clickhouse_data:/var/lib/clickhouse
    restart: always

volumes:
  clickhouse_data:
```
Let's break down this file:
- version: '3.7': Specifies the version of the Docker Compose file format.
- services:: Defines the services to be run.
- clickhouse-server:: Defines the ClickHouse server service.
- image: clickhouse/clickhouse-server: Specifies the image to use for the service.
- ports:: Maps the ports on the host machine to the container.
- volumes:: Defines the volumes to be used by the service. In this case, we're creating a named volume called clickhouse_data to persist the ClickHouse data across container restarts.
- restart: always: Ensures that the container is automatically restarted if it crashes.
Start the ClickHouse Container:

Open your terminal, navigate to the directory where you created the docker-compose.yml file, and run the following command:
```
docker-compose up -d
```
This command creates and starts the ClickHouse container in detached mode. Docker Compose automatically pulls the ClickHouse image if it's not already present on your system.
Verify the Installation:

To verify that ClickHouse is running correctly, you can use the docker ps command to list the running containers:
```
docker ps
```
You should see a container named "clickhouse-server" in the output. You can also use the ClickHouse client to connect to the server, as described in the previous method.

Connecting to ClickHouse

Now that you have ClickHouse running in a Docker container, you'll want to connect to it and start using it. Here are a few ways to connect:

Using the ClickHouse Client

As mentioned earlier, you can use the clickhouse-client command-line tool to connect to the ClickHouse server. If you're using the Docker CLI method, you can run the client inside the container:

    docker exec -it clickhouse-server clickhouse-client

If you're using Docker Compose, you can either run the client inside the container or install it directly on your host machine. To install the client on your host machine, follow the instructions in the ClickHouse documentation.

Once you're connected, you can start running SQL queries to create tables, insert data, and retrieve results. For example:

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

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

    SELECT * FROM my_table;

Using HTTP Interface

ClickHouse also provides an HTTP interface that you can use to interact with the server. By default, the HTTP interface listens on port 8123. You can send HTTP requests to the server to execute queries and retrieve results.

For example, you can use the curl command to send a query to the server:

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

This command sends a SELECT query to the server and retrieves the results in a tab-separated format.

Using Third-Party Tools

There are also various third-party tools and libraries that you can use to connect to ClickHouse, such as JDBC drivers, Python libraries, and more. These tools provide a more convenient way to interact with ClickHouse from your applications.

Persisting Data

One important thing to consider when running ClickHouse in a Docker container is data persistence. By default, the data stored in the container is lost when the container is stopped or removed. To avoid this, you need to persist the data to a volume on your host machine.

In the Docker Compose example above, we used a named volume called clickhouse_data to persist the data. This volume is automatically created by Docker and mounted to the /var/lib/clickhouse directory inside the container, which is where ClickHouse stores its data.

If you're using the Docker CLI method, you can achieve the same result by using the -v flag to mount a directory on your host machine to the /var/lib/clickhouse directory inside the container:

    docker run -d --name clickhouse-server -p 8123:8123 -p 9000:9000 -v /path/to/your/data:/var/lib/clickhouse clickhouse/clickhouse-server

Replace /path/to/your/data with the actual path to the directory on your host machine where you want to store the data. By persisting the data to a volume, you can ensure that your data is not lost when the container is stopped or removed.

Conclusion

So, there you have it! You've successfully installed ClickHouse using Docker. Whether you chose the Docker CLI or Docker Compose method, you now have a running ClickHouse instance ready for your data-crunching needs. Remember to persist your data using volumes to avoid any data loss. Now go forth and explore the incredible performance and features of ClickHouse! Happy querying, folks! This was a lot of content! Hopefully, you guys find this useful. If you want to learn more make sure you google it.