Installer ClickHouse avec Docker

Le guide sur Docker Hub est reproduit ci-dessous pour plus de commodité. Les images Docker disponibles utilisent les paquets deb officiels de ClickHouse.

Commande docker pull :

docker pull clickhouse/clickhouse-server

• Le tag latest pointe vers la dernière version publiée de la branche stable la plus récente.
• Les tags de branche comme 22.2 pointent vers la dernière version publiée de la branche correspondante.
• Les tags de version complets comme 22.2.3 et 22.2.3.5 pointent vers la version publiée correspondante.
• Le tag head est construit à partir du dernier commit de la branche default.
• Chaque tag peut avoir le suffixe facultatif -alpine, indiquant qu'il est construit sur alpine.

• L’image amd64 nécessite la prise en charge du niveau de microarchitecture x86-64-v3 (AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, XSAVE). Pratiquement tous les processeurs x86 commercialisés après 2015 prennent en charge x86-64-v3.
• L’image arm64 nécessite la prise en charge de l’architecture ARMv8.2-A ainsi que du registre Load-Acquire RCpc. Ce registre est facultatif dans ARMv8.2-A et obligatoire dans ARMv8.3-A. Pris en charge sur les instances Graviton >=2, Azure et GCP. Parmi les appareils non pris en charge figurent le Raspberry Pi 4 (ARMv8.0-A) et les Jetson AGX Xavier/Orin (ARMv8.2-A).
• Depuis ClickHouse 24.11, les images Ubuntu utilisent ubuntu:22.04 comme image de base. Cela nécessite Docker >= 20.10.10 avec le patch. Comme solution de contournement, vous pouvez utiliser docker run --security-opt seccomp=unconfined à la place, mais cela a des implications en matière de sécurité.

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

Par défaut, ClickHouse ne sera accessible que via le réseau Docker. Voir la section sur la mise en réseau ci-dessous.

Par défaut, l'instance du serveur ci-dessus sera exécutée sous l'utilisateur default, sans mot de passe.

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

Voir client ClickHouse pour plus d’informations sur le client ClickHouse.

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

Voir ClickHouse HTTP Interface pour en savoir plus sur l’interface HTTP.

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

Vous pouvez exposer votre instance ClickHouse exécutée dans Docker en mappant un port spécifique depuis l’intérieur du conteneur à l’aide des ports de l’hôte :

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 @-

Ou en permettant au conteneur d'utiliser les ports de l'hôte directement avec --network=host (ce qui permet aussi d'obtenir de meilleures performances réseau) :

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 @-

En général, vous souhaiterez monter les dossiers suivants dans votre conteneur afin d'assurer la persistance :

• /var/lib/clickhouse/ - dossier principal où ClickHouse stocke les données
• /var/log/clickhouse-server/ - logs

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

Vous pouvez également monter :

• /etc/clickhouse-server/config.d/*.xml - fichiers contenant des ajustements de la configuration du serveur
• /etc/clickhouse-server/users.d/*.xml - fichiers contenant des ajustements des paramètres utilisateur
• /docker-entrypoint-initdb.d/ - dossier contenant les scripts d'initialisation de la base de données (voir ci-dessous).

ClickHouse dispose de fonctionnalités avancées qui nécessitent l’activation de plusieurs capabilities Linux

Elles sont facultatives et peuvent être activées à l’aide des arguments de ligne de commande Docker suivants :

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

Pour en savoir plus, consultez "Configuration des capacités CAP_IPC_LOCK et CAP_SYS_NICE dans Docker"

Le conteneur expose le port 8123 pour l’interface HTTP et le port 9000 pour le client natif.

La configuration de ClickHouse est définie dans un fichier "config.xml" (documentation)

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

Lorsque vous utilisez l’image avec des répertoires locaux montés, vous devrez probablement préciser l’utilisateur afin de conserver les bons propriétaires de fichiers. Utilisez l’argument --user et montez /var/lib/clickhouse et /var/log/clickhouse-server dans le conteneur. Sinon, l’image signalera une erreur et ne démarrera pas.

Démarrer le serveur en tant que root est utile lorsque l’espace de noms utilisateur est activé. Pour ce faire, exécutez :

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

Il peut arriver que vous souhaitiez créer un utilisateur (l'utilisateur nommé default est utilisé par défaut) et une base de données au démarrage d'un conteneur. Vous pouvez le faire à l'aide des variables d'environnement CLICKHOUSE_DB, CLICKHOUSE_USER, CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT et 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

L’utilisateur default a l’accès réseau désactivé par défaut si aucune des variables CLICKHOUSE_USER, CLICKHOUSE_PASSWORD ou CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT n’est définie.

Il est possible de rendre l’utilisateur default accessible de manière non sécurisée en définissant la variable d’environnement CLICKHOUSE_SKIP_USER_SETUP sur 1 :

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

Pour effectuer une initialisation supplémentaire dans une image dérivée de celle-ci, ajoutez un ou plusieurs scripts *.sql, *.sql.gz ou *.sh dans /docker-entrypoint-initdb.d. Une fois initdb appelé par le point d’entrée, tous les fichiers *.sql seront exécutés, tous les scripts *.sh exécutables seront lancés et tous les scripts *.sh non exécutables trouvés dans ce répertoire seront chargés afin d’effectuer une initialisation supplémentaire avant le démarrage du service.

Vous pouvez également définir les variables d’environnement CLICKHOUSE_USER & CLICKHOUSE_PASSWORD, qui seront utilisées par clickhouse-client pendant l’initialisation.

Par exemple, pour ajouter un autre utilisateur et une autre base de données, ajoutez ce qui suit à /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