Перейти к основному содержанию
Перейти к основному содержанию

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

Подключение с помощью 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 Interface.

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

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

Сеть​

Примечание

Предопределённый пользователь default не имеет сетевого доступа, пока для него не задан пароль, см. разделы "How to create default database and user on starting" и "Managing default user" ниже.

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

Томa​

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

  • /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 (capabilities).

Они не являются обязательными и могут быть включены с помощью следующих аргументов командной строки 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 должна существовать и принадлежать текущему пользователю \{#pwddataclickhouse-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 и подключит (source) все неисполняемые скрипты *.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