Saltar al contenido principal

​
Instalar ClickHouse con Docker

La guía de Docker Hub se reproduce a continuación para mayor comodidad. Las imágenes de Docker disponibles usan los paquetes deb oficiales de ClickHouse. Comando docker pull: 
docker pull clickhouse/clickhouse-server

​
Versiones

  • La etiqueta latest apunta a la versión más reciente de la rama estable más reciente.
  • Las etiquetas de rama, como 22.2, apuntan a la versión más reciente de la rama correspondiente.
  • Las etiquetas de versión completa, como 22.2.3 y 22.2.3.5, apuntan a la versión correspondiente.
  • La etiqueta head se genera a partir del commit más reciente de la rama predeterminada.
  • Cada etiqueta tiene un sufijo opcional, -alpine, para indicar que se ha generado sobre alpine.

​
Compatibilidad

  • La imagen amd64 requiere compatibilidad con las instrucciones SSE3. Prácticamente todas las CPU x86 posteriores a 2005 son compatibles con SSE3.
  • La imagen arm64 requiere compatibilidad con la arquitectura ARMv8.2-A y además con el registro Load-Acquire RCpc. El registro es opcional en la versión ARMv8.2-A y obligatorio en ARMv8.3-A. Es compatible con instancias Graviton >=2 y con instancias de Azure y GCP. Algunos ejemplos de dispositivos no compatibles son Raspberry Pi 4 (ARMv8.0-A) y Jetson AGX Xavier/Orin (ARMv8.2-A).
  • A partir de ClickHouse 24.11, las imágenes de Ubuntu pasaron a usar ubuntu:22.04 como imagen base. Requiere Docker >= 20.10.10 que incluya el parche. Como solución alternativa, puede usar docker run --security-opt seccomp=unconfined; sin embargo, esto tiene implicaciones de seguridad.

​
Cómo utilizar esta imagen

​
Iniciar la instancia del servidor

docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
De forma predeterminada, ClickHouse solo será accesible a través de la red de Docker. Consulte la sección de redes más abajo. De forma predeterminada, la instancia del servidor anterior se ejecutará como el usuario default, sin contraseña.

​
Conéctese desde un cliente nativo

docker run -it --rm --network=container:some-clickhouse-server --entrypoint clickhouse-client clickhouse/clickhouse-server
# O
docker exec -it some-clickhouse-server clickhouse-client
Consulta ClickHouse client para obtener más información sobre el ClickHouse client.

​
Conectarse con 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 @-
Consulta la ClickHouse HTTP Interface para obtener más información sobre la interfaz HTTP.

​
Detener / eliminar el contenedor

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

​
Red

el usuario predefinido default no tiene acceso de red a menos que se establezca una contraseña; consulta “Cómo crear la base de datos y el usuario predeterminados al iniciar” y “Gestionar el usuario default” más abajo
Puedes exponer tu ClickHouse en ejecución en Docker asignando un puerto específico desde el interior del contenedor mediante puertos del host: 
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 @-
O permitiendo que el contenedor use directamente los puertos del host con --network=host (lo que también permite obtener un mejor rendimiento de red): 
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 @-
El usuario predeterminado del ejemplo anterior está disponible solo para las peticiones desde localhost

​
Volúmenes

Normalmente, conviene montar las siguientes carpetas dentro del contenedor para garantizar la persistencia:
  • /var/lib/clickhouse/ - carpeta principal donde ClickHouse almacena los datos
  • /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
También puede montar:
  • /etc/clickhouse-server/config.d/*.xml - archivos con ajustes de configuración del servidor
  • /etc/clickhouse-server/users.d/*.xml - archivos con ajustes de configuración de usuarios
  • /docker-entrypoint-initdb.d/ - carpeta con scripts de inicialización de la base de datos (consulte más abajo).

​
Capacidades de Linux

ClickHouse cuenta con algunas funciones avanzadas que requieren habilitar varias capacidades de Linux Son opcionales y se pueden habilitar con los siguientes argumentos de la línea de comandos de 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
Para más información, consulte “Configuración de las capacidades CAP_IPC_LOCK y CAP_SYS_NICE en Docker”

​
Configuración

El contenedor expone el puerto 8123 para la interfaz HTTP y el puerto 9000 para el cliente nativo. La configuración de ClickHouse se define en el archivo “config.xml” (documentación)

​
Iniciar una instancia del servidor con una configuración personalizada

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

​
Iniciar el servidor con un usuario personalizado

# $PWD/data/clickhouse debe existir y pertenecer al usuario actual
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
Cuando use la imagen con directorios locales montados, probablemente le convenga especificar el usuario para mantener la propiedad correcta de los archivos. Use el argumento --user y monte /var/lib/clickhouse y /var/log/clickhouse-server dentro del contenedor. De lo contrario, la imagen mostrará un error y no se iniciará.

​
Iniciar el servidor desde root

Iniciar el servidor desde root es útil en los casos en que el espacio de nombres de usuario está habilitado. Para hacerlo, ejecute: 
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

​
Cómo crear una base de datos y un usuario predeterminados al iniciar

A veces puede que quieras crear un usuario (de forma predeterminada se usa un usuario llamado default) y una base de datos al iniciar el contenedor. Puedes hacerlo mediante las variables de entorno CLICKHOUSE_DB, CLICKHOUSE_USER, CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT y 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

​
Gestión del usuario default

El usuario default tiene el acceso de red deshabilitado de forma predeterminada si no se establece ninguno de estos valores: CLICKHOUSE_USER, CLICKHOUSE_PASSWORD o CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT. Hay una forma de hacer que el usuario default esté disponible de forma no segura: estableciendo la variable de entorno CLICKHOUSE_SKIP_USER_SETUP en 1: 
docker run --rm -e CLICKHOUSE_SKIP_USER_SETUP=1 -p 9000:9000/tcp clickhouse/clickhouse-server

​
Cómo extender esta imagen

Para realizar una inicialización adicional en una imagen derivada de esta, agregue uno o varios scripts *.sql, *.sql.gz o *.sh en /docker-entrypoint-initdb.d. Después de que el entrypoint llame a initdb, ejecutará todos los archivos *.sql, ejecutará todos los scripts *.sh ejecutables y cargará todos los scripts *.sh no ejecutables que encuentre en ese directorio para completar la inicialización antes de iniciar el servicio.
Los scripts de /docker-entrypoint-initdb.d se ejecutan en orden alfabético según el nombre del archivo. Si sus scripts dependen unos de otros (por ejemplo, un script que crea vistas debe ejecutarse después del script que crea las tablas a las que hacen referencia), asegúrese de que los nombres de archivo queden ordenados correctamente.
Además, puede proporcionar las variables de entorno CLICKHOUSE_USER & CLICKHOUSE_PASSWORD, que se usarán con clickhouse-client durante la inicialización. Por ejemplo, para agregar otro usuario y otra base de datos, añada lo siguiente a /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
Última modificación el 10 de junio de 2026