1. Introduction

Running ClickHouse locally is one of the most practical ways to learn, experiment, and build analytical applications, and Docker makes this process significantly simpler by removing the need for manual installation and dependency management. In this chapter-style tutorial, you will learn how to run ClickHouse using Docker, understand why each step is performed, and develop a clear conceptual model of how containers host a database system like ClickHouse.

Docker is an open-source platform that helps developers build, deploy, run, and manage containers, and containers are lightweight, standalone packages that include everything required to run a software application, such as the runtime, system tools, libraries, and configuration. Because of this packaging model, the application behaves consistently across different environments, which is extremely valuable for databases like ClickHouse.

This tutorial focuses specifically on running ClickHouse using Docker rather than installing Docker itself, so Docker Engine must already be installed on your machine before proceeding.

2. Understanding the Objective

Before typing commands, it is important to understand the objective at a conceptual level, because Docker becomes much easier when you understand what is happening behind the scenes. Our goal is to run a ClickHouse server inside a Docker container so that we can interact with it using the ClickHouse client.

An image in Docker is a read-only template that contains the application and its dependencies, while a container is a running instance of that image. When you run ClickHouse in Docker, you are not installing it on your operating system in the traditional sense, but instead running it inside an isolated environment.

This isolation ensures that your local system remains clean and that ClickHouse can be started, stopped, or removed without affecting other software.

3. Understanding Docker Hub and ClickHouse Images

Docker Hub is a public registry where container images are published by software vendors, open-source projects, and community members, and it serves as the default location from which Docker pulls images.

There are multiple ClickHouse images available, but the recommended choice is the official image maintained by the ClickHouse development team because it is reliable, updated regularly, and aligned with official best practices.

The official image is:

clickhouse/clickhouse-server

Using the official image reduces risk and ensures compatibility with documentation and updates.

4. Running ClickHouse Server in Docker

Running ClickHouse involves creating and starting a container from the official ClickHouse image while configuring system limits suitable for a high-performance database.

A typical command looks like this:

docker run -d --name ch-server -p 8123:8123 -p 8090:8090 -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=admin --ulimit nofile=262144:262144 clickhouse/clickhouse-server:latest

Each part of this command has a purpose.

• The docker run command creates and starts a container from an image in a single step.
• The -d flag runs the container in detached mode so that it runs in the background.
• The --name ch-server option assigns a readable name to the container for easier management.
• The --ulimit nofile=262144:262144 option increases the allowed number of open files, which ClickHouse benefits from due to its internal design and heavy I/O usage.
• The :latest tag tells Docker to use the most recent image version.

The ulimit setting comes from Linux resource controls and helps avoid bottlenecks when ClickHouse handles many files or connections.

We have also specified the password for the default user.

5. Entering the Container

To interact directly with the container environment, Docker provides the exec command, which allows you to run commands inside a running container.

docker exec -it ch-server /bin/bash

The -it flags provide an interactive terminal session.
/bin/bash starts a shell inside the container.

After this command, your terminal session is operating inside the container.

6. Connecting with ClickHouse Client

The official ClickHouse server image already includes the ClickHouse client, which simplifies usage because no additional installation is required.

Inside the container, run:

clickhouse-client

If the connection is successful, you will see the ClickHouse prompt where SQL queries can be executed.

For example:

 SHOW DATABASES;

This confirms that the server is running and responding.

C:\Users>docker exec -it 0ae52 /bin/bash
root@0ae52516071a:/# clickhouse-client
ClickHouse client version 26.1.2.11 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 26.1.2.

Warnings:
 * Delay accounting is not enabled, OSIOWaitMicroseconds will not be gathered. You can enable it using `sudo sh -c 'echo 1 > /proc/sys/kernel/task_delayacct'` or by using sysctl.

0ae52516071a :) SHOW DATABASES;

SHOW DATABASES

Query id: 09dfce5e-2299-4fc9-8f07-fa37ee6aa192

   ┌─name───────────────┐
1. │ INFORMATION_SCHEMA │
2. │ default            │
3. │ information_schema │
4. │ system             │
   └────────────────────┘

4 rows in set. Elapsed: 0.006 sec.