Установка ClickHouse через Docker

Для удобства ниже приводится руководство с 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 требует поддержки инструкций SSE3. Практически все процессоры x86, выпущенные после 2005 года, поддерживают SSE3.
Образ 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, содержащая patch. В качестве обходного решения можно использовать 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
# ИЛИ
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

Сеть

у предопределённого пользователя default нет доступа к сети, если не задан пароль, см. “Как создать базу данных и пользователя по умолчанию при запуске” и “Управление пользователем default” ниже

Вы можете открыть доступ к 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 @-

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

Тома

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

/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/ - каталог со скриптами инициализации базы данных (см. ниже).

Привилегии 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 должен существовать и принадлежать текущему пользователю
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

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

Иногда при запуске контейнера может потребоваться создать пользователя (по умолчанию используется пользователь с именем default) и database. Это можно сделать с помощью переменных окружения 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 и обработает через source все неисполняемые скрипты *.sh, найденные в этом каталоге, чтобы выполнить дополнительную инициализацию перед запуском сервиса.

Скрипты в /docker-entrypoint-initdb.d выполняются в алфавитном порядке по имени файла. Если ваши скрипты зависят друг от друга (например, скрипт, создающий представления, должен выполняться после скрипта, создающего таблицы, на которые они ссылаются), убедитесь, что имена файлов сортируются в правильном порядке.

Кроме того, вы можете задать переменные окружения CLICKHOUSE_USER и CLICKHOUSE_PASSWORD, которые будут использоваться для clickhouse-client во время инициализации. Например, чтобы добавить ещё одного пользователя и базу данных, добавьте следующее в /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

​Установка ClickHouse через Docker

​Версии

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

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

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

​Подключитесь к нему из нативного клиента

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

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

​Сеть

​Тома

​Привилегии Linux

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

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

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

​Запуск сервера от root

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

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

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

Установка ClickHouse через Docker

Версии

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

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

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

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

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

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

Сеть

Тома

Привилегии Linux

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

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

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

Запуск сервера от root

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

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

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