ClickHouse Docker: установка и запуск через Docker Compose

Самый быстрый способ попробовать ClickHouse локально — запустить официальный Docker-образ. За пару команд вы получите сервер, HTTP-интерфейс на порту 8123, native-клиент на порту 9000 и сможете выполнить первый SQL-запрос без ручной установки пакетов

Когда выбирать Docker

Docker удобен для обучения, локальной разработки, тестовых стендов и быстрых экспериментов. Он не требует менять системные репозитории, легко удаляется и позволяет держать данные в отдельном volume. Если ClickHouse нужен на production-сервере, дополнительно изучайте пакетную установку, мониторинг, backup, users.xml, TLS и ограничения ресурсов

Быстрый запуск одной командой

Для первого запуска достаточно official image clickhouse/clickhouse-server. Важный параметр — --ulimit nofile=262144:262144. ClickHouse активно работает с файлами, поэтому низкий лимит файловых дескрипторов может привести к проблемам на реальных нагрузках

docker run -d --name clickhouse-server \
  --ulimit nofile=262144:262144 \
  -p 8123:8123 -p 9000:9000 \
  clickhouse/clickhouse-server

Проверьте, что контейнер запущен:

docker ps

Как подключиться через clickhouse-client

Самый простой вариант — открыть клиент внутри контейнера:

docker exec -it clickhouse-server clickhouse-client

Внутри клиента выполните проверку:

SELECT version(), currentDatabase();

Если ответ вернулся, сервер работает. По умолчанию вы подключаетесь к пользователю default и базе default

Порты 8123 и 9000

Путаница портов — частая причина ошибок. Если драйвер ожидает HTTP, используйте 8123. Если подключаетесь native-клиентом с хоста, чаще нужен 9000

Проверка через HTTP

curl 'http://localhost:8123/?query=SELECT%201'

Можно отправить полноценный SQL-запрос:

echo "SELECT 'Hello, ClickHouse!'" | \
  curl 'http://localhost:8123/?query=' --data-binary @-

Docker Compose для нормальной локальной работы

Для постоянной работы лучше использовать Docker Compose и volumes. Тогда данные и логи не исчезнут после пересоздания контейнера

services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    container_name: clickhouse-server
    ports:
      - "8123:8123"
      - "9000:9000"
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    volumes:
      - clickhouse-data:/var/lib/clickhouse
      - clickhouse-logs:/var/log/clickhouse-server
volumes:
  clickhouse-data:
  clickhouse-logs:

Запуск:

docker compose up -d
docker compose logs -f clickhouse

Минимальная проверка после запуска

docker exec -it clickhouse-server clickhouse-client
CREATE DATABASE IF NOT EXISTS demo;
CREATE TABLE demo.ping
(
    ts DateTime,
    message String
)
ENGINE = MergeTree
ORDER BY ts;
INSERT INTO demo.ping VALUES (now(), 'ok');
SELECT * FROM demo.ping;

Как задать пароль

Для локального обучения часто стартуют без пароля. Для сетевого доступа и командной работы задавайте пользователя и пароль через конфигурацию или переменные окружения образа. Не публикуйте контейнер с открытыми портами наружу без аутентификации, TLS и firewall

Частые ошибки

• Порт занят. Проверьте, не запущен ли другой ClickHouse или сервис на 8123/9000.
• Нет volume. Данные внутри контейнера могут потеряться при пересоздании.
• Забыли ulimit. На тесте может быть незаметно, на нагрузке приведет к ошибкам.
• Путаете localhost внутри контейнера и на хосте. В Docker Compose сервисы общаются по имени сервиса.
• Драйвер подключается не к тому протоколу. HTTP и native используют разные порты.

Минимальная структура локального проекта

Чтобы не держать команды в истории терминала, заведите маленькую папку проекта. В ней достаточно docker-compose.yml, папки для SQL-скриптов и README с командами запуска

clickhouse-demo/
├── docker-compose.yml
├── sql/
│   ├── 01-create-tables.sql
│   └── 02-insert-demo-data.sql
└── README.md

SQL-файлы можно выполнять через клиент:

docker exec -i clickhouse-server clickhouse-client < sql/01-create-tables.sql
docker exec -i clickhouse-server clickhouse-client < sql/02-insert-demo-data.sql

Такой подход удобен для повторяемости: если контейнер нужно пересоздать, вы быстро поднимаете схему и тестовые данные заново. Это особенно полезно при подготовке уроков, демо и локальных экспериментов

Что не делать в локальном Docker-стенде

• Не публикуйте порты ClickHouse в публичную сеть без пароля и firewall.
• Не храните важные данные только внутри контейнера без volume.
• Не используйте тег latest для production без контроля версии.
• Не смешивайте учебный стенд и рабочие данные в одном volume.

Что сделать после запуска контейнера

Как понять, что установка не просто запустилась, а готова к учебе?

Проверьте не только SELECT version(), а полный маленький сценарий: база, таблица, вставка и агрегирующий запрос. Следующий шаг разобран в уроке CREATE TABLE в ClickHouse: MergeTree, ORDER BY и база данных

Что лучше вынести в отдельные файлы сразу?

Минимум — docker-compose.yml, SQL для создания таблиц и отдельный файл с тестовыми вставками. Так вы не теряете ход эксперимента и можете быстро повторить стенд перед уроком про ClickHouse Client, INSERT INTO и первые SELECT-запросы

Когда Docker-стенд уже недостаточен?

Когда появляются реальные данные, права пользователей, бэкапы, мониторинг и сетевой доступ для команды. Для локального обучения Docker удобен, но перед интеграцией с приложением стоит отдельно проверить подключение ClickHouse из Python, JDBC, ODBC и Power BI