Установка ClickHouse с использованием Docker

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

Команда для загрузки Docker:

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, содержащей патч. В качестве обходного решения вы можете использовать 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 client для получения дополнительной информации о клиенте 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 @-

См. ClickHouse HTTP Interface для получения дополнительной информации о HTTP интерфейсе.

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

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

Сеть

примечание

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

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

docker run -d -p 18123:8123 -p 19000: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 @-

примечание

Пользователь default в приведенном выше примере доступен только для запросов 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

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

Иногда вы можете захотеть создать пользователя (по умолчанию используется пользователь с именем 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. После вызова точки входа initdb, будут выполнены все файлы *.sql, исполняемые скрипты *.sh и скрипты *.sh, которые не являются исполняемыми, найденные в этой директории, чтобы провести дальнейшую инициализацию перед запуском сервиса.
Также вы можете предоставить переменные окружения 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 = Log;
EOSQL