Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Установка ClickHouse с помощью Docker

View as MarkdownEdit this pageReport an issueSet up docs MCP

Для удобства ниже приводится руководство с Docker Hub. Доступные Docker-образы используют официальные deb-пакеты ClickHouse.

Команда Docker pull:

docker pull clickhouse/clickhouse-server

Версии

  • Тег latest указывает на последний релиз последней стабильной ветки.
  • Теги веток, такие как 22.2, указывают на последний релиз соответствующей ветки.
  • Теги полной версии, такие как 22.2.3 и 22.2.3.5, указывают на соответствующий релиз.
  • Тег head собирается из последнего коммита в ветке по умолчанию.
  • У каждого тега может быть необязательный суффикс -alpine, который указывает, что он собран на основе alpine.

Совместимость

  • Для образа amd64 требуется поддержка уровня микроархитектуры x86-64-v3 (AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, XSAVE). Практически все CPU x86, выпущенные после 2015 года, поддерживают x86-64-v3.
  • Для образа arm64 требуется поддержка архитектуры ARMv8.2-A и дополнительно регистра Load-Acquire RCpc. В ARMv8.2-A этот регистр является необязательным, а в ARMv8.3-A — обязательным. Поддерживается в Graviton >=2, а также в экземплярах Azure и GCP. Примеры неподдерживаемых устройств: Raspberry Pi 4 (ARMv8.0-A) и Jetson AGX Xavier/Orin (ARMv8.2-A).
  • Начиная с ClickHouse 24.11 образы Ubuntu используют ubuntu:22.04 в качестве базового образа. Для этого требуется Docker версии >= 20.10.10, включающей патч. В качестве обходного пути можно использовать docker run --security-opt seccomp=unconfined, однако это имеет последствия для безопасности.

Как использовать этот образ

Запустите экземпляр сервера

docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server

По умолчанию ClickHouse будет доступен только через сеть Docker. См. раздел о настройке сети ниже.

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

Подключитесь к нему через нативный клиент

docker run -it --rm --network=container:some-clickhouse-server --entrypoint clickhouse-client clickhouse/clickhouse-server
# OR
docker exec -it some-clickhouse-server clickhouse-client

См. клиент ClickHouse, чтобы узнать больше о клиенте ClickHouse.

Подключитесь к нему с помощью curl

echo "SELECT 'Hello, ClickHouse!'" | docker run -i --rm --network=container:some-clickhouse-server buildpack-deps:curl curl 'http://localhost:8123/?query=' -s --data-binary @-

См. HTTP-интерфейс ClickHouse, чтобы узнать больше об HTTP-интерфейсе.

Остановка и удаление контейнера

docker stop some-clickhouse-server
docker rm some-clickhouse-server

Сеть

Вы можете открыть доступ к ClickHouse, запущенному в Docker, пробросив нужный порт из контейнера на порт хоста:

docker run -d -p 18123:8123 -p19000:9000 -e CLICKHOUSE_PASSWORD=changeme --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
echo 'SELECT version()' | curl 'http://localhost:18123/?password=changeme' --data-binary @-

Или разрешив контейнеру использовать порты хоста напрямую с помощью --network=host (это также позволяет добиться более высокой сетевой производительности):

docker run -d --network=host --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
echo 'SELECT version()' | curl 'http://localhost:8123/' --data-binary @-

Тома

Обычно, чтобы обеспечить сохранность данных, в контейнер монтируют следующие папки:

  • /var/lib/clickhouse/ - основная папка, в которой ClickHouse хранит данные
  • /var/log/clickhouse-server/ - журналы
docker run -d \
    -v "$PWD/ch_data:/var/lib/clickhouse/" \
    -v "$PWD/ch_logs:/var/log/clickhouse-server/" \
    --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server

При необходимости можно также смонтировать:

  • /etc/clickhouse-server/config.d/*.xml - файлы с изменениями конфигурации сервера
  • /etc/clickhouse-server/users.d/*.xml - файлы с изменениями пользовательских настроек
  • /docker-entrypoint-initdb.d/ - каталог со script инициализации базы данных (см. ниже).

Привилегии Linux

В ClickHouse есть некоторые расширенные возможности, для работы которых требуется включить несколько привилегий Linux

Они необязательны, и их можно включить с помощью следующих аргументов командной строки Docker:

docker run -d \
    --cap-add=SYS_NICE --cap-add=NET_ADMIN --cap-add=IPC_LOCK \
    --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server

Подробнее см. в "Настройка привилегий CAP_IPC_LOCK и CAP_SYS_NICE в Docker"

Конфигурация

Контейнер использует порт 8123 для HTTP-интерфейса и порт 9000 для нативного клиента.

Конфигурация ClickHouse задается файлом "config.xml" (документация)

Запустите экземпляр сервера с пользовательской конфигурацией

docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 -v /path/to/your/config.xml:/etc/clickhouse-server/config.xml clickhouse/clickhouse-server

Запуск сервера от имени другого пользователя

# $PWD/data/clickhouse should exist and be owned by current user
docker run --rm --user "${UID}:${GID}" --name some-clickhouse-server --ulimit nofile=262144:262144 -v "$PWD/logs/clickhouse:/var/log/clickhouse-server" -v "$PWD/data/clickhouse:/var/lib/clickhouse" clickhouse/clickhouse-server

Когда вы используете образ со смонтированными локальными каталогами, скорее всего, вам стоит указать пользователя, чтобы сохранить корректные права владения файлами. Используйте аргумент --user и смонтируйте /var/lib/clickhouse и /var/log/clickhouse-server внутри контейнера. В противном случае образ выдаст ошибку и не запустится.

Запуск сервера из-под root

Запуск сервера из-под root полезен в случаях, когда включено пространство имен пользователя. Для этого выполните:

docker run --rm -e CLICKHOUSE_RUN_AS_ROOT=1 --name clickhouse-server-userns -v "$PWD/logs/clickhouse:/var/log/clickhouse-server" -v "$PWD/data/clickhouse:/var/lib/clickhouse" clickhouse/clickhouse-server

Как при запуске создать базу данных и пользователя по умолчанию

Иногда при запуске контейнера требуется создать пользователя (по умолчанию используется пользователь с именем default) и базу данных. Это можно сделать с помощью переменных окружения CLICKHOUSE_DB, CLICKHOUSE_USER, CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT и CLICKHOUSE_PASSWORD:

docker run --rm -e CLICKHOUSE_DB=my_database -e CLICKHOUSE_USER=username -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 -e CLICKHOUSE_PASSWORD=password -p 9000:9000/tcp clickhouse/clickhouse-server

Управление пользователем default

Для пользователя default сетевой доступ по умолчанию отключён, если не заданы CLICKHOUSE_USER, CLICKHOUSE_PASSWORD или CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT.

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

docker run --rm -e CLICKHOUSE_SKIP_USER_SETUP=1 -p 9000:9000/tcp clickhouse/clickhouse-server

Как расширить этот образ

Чтобы выполнить дополнительную инициализацию в образе, производном от этого, добавьте один или несколько скриптов *.sql, *.sql.gz или *.sh в /docker-entrypoint-initdb.d. После того как entrypoint вызовет initdb, он выполнит все файлы *.sql, запустит все исполняемые скрипты *.sh и подключит все неисполняемые скрипты *.sh, найденные в этом каталоге, чтобы завершить инициализацию перед запуском сервиса.

Кроме того, вы можете указать переменные окружения CLICKHOUSE_USER и CLICKHOUSE_PASSWORD, которые будут использоваться клиентом ClickHouse во время инициализации.

Например, чтобы добавить ещё одного пользователя и базу данных, добавьте следующее в /docker-entrypoint-initdb.d/init-db.sh:

#!/bin/bash
set -e

clickhouse client -n <<-EOSQL
    CREATE DATABASE docker;
    CREATE TABLE docker.docker (x Int32) ENGINE = MergeTree
    ORDER BY ();
EOSQL
Navigation