Getting Started with ClickHouse®: OSS – Installation and Setup

In our previous article, What is ClickHouse®? A Beginner’s Guide to the OLAP Database, we explored what ClickHouse® is, why it was created, and how it differs from traditional databases.

Now it’s time to get hands-on.

In this guide, we’ll walk through the most beginner-friendly ways to install ClickHouse® and verify that everything is working correctly. By the end of this article, you’ll have a running ClickHouse® instance and be ready to execute your first queries.

Choosing an Installation Method

ClickHouse® can be deployed in several ways depending on your environment and requirements.

For beginners, we recommend starting with Docker Compose because it is simple, portable, and works consistently across Linux, Windows, and macOS.

Prerequisites

Before installing ClickHouse®, make sure you have the following tools available on your system.

Linux

Install:

• Docker Engine
• Docker Compose

Verify the installation:

docker --version
docker compose version

Windows

Install Docker Desktop and verify:

docker --version
docker compose version

macOS

Install Docker Desktop and verify:

docker --version
docker compose version

Installing ClickHouse® Using Docker Compose

Docker Compose provides one of the fastest ways to get ClickHouse® running locally.

Create a file named:

docker-compose.yml

Add the following configuration:

services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    container_name: clickhouse-server
    ports:
      - "8123:8123"
      - "9000:9000"
    volumes:
      - clickhouse_data:/var/lib/clickhouse
    restart: unless-stopped
 
volumes:
  clickhouse_data:

Start ClickHouse®:

docker compose up -d

Docker will pull the ClickHouse® image and start the server in the background.

Verify the Container Status

Run:

docker ps

You should see a running container named clickhouse-server.

Connecting to ClickHouse®

Once the container is running, connect to the ClickHouse® client:

docker exec -it clickhouse-server clickhouse-client

If everything is configured correctly, you’ll see a successful connection message and an interactive SQL prompt.

Running Your First Query

Let’s verify that ClickHouse® is working correctly.

Execute:

SELECT version();

Example output:

┌─version()─┐
│ 26.x.x.x  │
└───────────┘

This confirms that your ClickHouse® server is operational.

Creating Your First Database

Next, create a database:

CREATE DATABASE tutorial;

Verify that it exists:

SHOW DATABASES;

You should see the newly created database in the results.

This simple exercise confirms that ClickHouse® is accepting commands and storing metadata correctly.

Alternative Method: Installing ClickHouse® on Ubuntu/Debian

If you’re planning to run ClickHouse® directly on a Linux server, Ubuntu/Debian is one of the most common deployment environments.

Setup Debian repository

To install ClickHouse® run the following commands:

# Install prerequisite packages
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
 
# Download the ClickHouse GPG key and store it in the keyring
curl -fsSL 'https://packages.clickhouse.com/rpm/lts/repodata/repomd.xml.key' | sudo gpg --dearmor -o /usr/share/keyrings/clickhouse-keyring.gpg
 
# Get the system architecture
ARCH=$(dpkg --print-architecture)
 
# Add the ClickHouse repository to apt sources
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg arch=${ARCH}] https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
 
# Update apt package lists
sudo apt-get update

Install ClickHouse® server and client:

sudo apt-get install -y clickhouse-server clickhouse-client

Start the client:

clickhouse-client

Verify the installation:

SELECT version();

While Docker is ideal for learning and development, native installations are often used in production environments.

Common Ports Used by ClickHouse®

When working with ClickHouse®, you’ll frequently encounter these ports:

The Docker Compose configuration exposes both ports so that applications and clients can communicate with the database.

Troubleshooting Tips

Container Not Starting

Check container logs:

docker logs clickhouse-server

Cannot Connect to ClickHouse®

Verify that the container is running:

docker ps

Port Already in Use

Check whether another service is using ports 8123 or 9000 and stop the conflicting application.

Final Thoughts

Installing ClickHouse® is surprisingly straightforward, especially with Docker Compose. Within a few minutes, you can have a fully functional analytical database running on your local machine.

For beginners, Docker provides the quickest path to learning and experimentation, while Ubuntu installations and ClickHouse® Cloud offer options for production and managed environments.

The important part is getting started. Once ClickHouse® is running, you can begin exploring the powerful features that make it one of the most popular OLAP databases today.

Exploring ClickHouse® for Your Analytics?

At Quantrail Data, we help teams run ClickHouse® reliably for real-time analytics – from Kubernetes deployments and migrations to performance tuning in production.

We see these challenges firsthand while supporting demanding analytics workloads. In one recent engagement, a customer achieved near bare-metal performance with ClickHouse® in production – a story we’ve shared here:

Success Story: Quantrail Bare-Metal ClickHouse® Deployment

If you’re evaluating ClickHouse® or trying to get more out of an existing setup, we’re happy to share practical lessons from real-world deployments.

Contact – Quantrail Data

References

What is ClickHouse®? A Beginner’s Guide to the OLAP Database
ClickHouse® Installation Docs