Pular para o conteúdo principal

​
Instale o ClickHouse usando Docker

O guia no Docker Hub é reproduzido abaixo para facilitar. As imagens Docker disponíveis usam os pacotes deb oficiais do ClickHouse. Comando docker pull: 
docker pull clickhouse/clickhouse-server

​
Versões

  • A tag latest aponta para o lançamento mais recente da branch estável mais atual.
  • Tags de branch como 22.2 apontam para o lançamento mais recente da branch correspondente.
  • Tags de versão completa como 22.2.3 e 22.2.3.5 apontam para o lançamento correspondente.
  • A tag head é gerada com base no commit mais recente da branch padrão.
  • Cada tag tem o sufixo opcional -alpine, indicando que foi gerada com base em alpine.

​
Compatibilidade

  • A imagem amd64 requer suporte a instruções SSE3. Praticamente todas as CPUs x86 após 2005 oferecem suporte a SSE3.
  • A imagem arm64 requer suporte à arquitetura ARMv8.2-A e, adicionalmente, ao registrador Load-Acquire RCpc. O registrador é opcional na versão ARMv8.2-A e obrigatório na ARMv8.3-A. Compatível com instâncias Graviton >=2, Azure e GCP. Exemplos de dispositivos não compatíveis são Raspberry Pi 4 (ARMv8.0-A) e Jetson AGX Xavier/Orin (ARMv8.2-A).
  • Desde o ClickHouse 24.11, as imagens Ubuntu passaram a usar ubuntu:22.04 como imagem base. Isso requer o Docker na versão >= 20.10.10, contendo o patch. Como alternativa, você pode usar docker run --security-opt seccomp=unconfined, porém isso tem implicações de segurança.

​
Como usar esta imagem

​
Iniciar a instância do servidor

docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
Por padrão, o ClickHouse ficará acessível apenas pela rede do Docker. Consulte a seção de rede abaixo. Por padrão, a instância do servidor iniciada acima será executada como o usuário default, sem senha.

​
Conecte-se a ele usando um cliente nativo

docker run -it --rm --network=container:some-clickhouse-server --entrypoint clickhouse-client clickhouse/clickhouse-server
# OU
docker exec -it some-clickhouse-server clickhouse-client
Consulte o ClickHouse client para obter mais informações.

​
Conecte-se usando 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 @-
Consulte a ClickHouse HTTP Interface para obter mais informações sobre a interface HTTP.

​
Parando / removendo o container

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

​
Rede

o usuário predefinido default não tem acesso à rede, a menos que a senha seja definida; veja “Como criar o banco de dados e o usuário padrão na inicialização” e “Gerenciar o usuário default” abaixo
Você pode expor o ClickHouse em execução no Docker mapeando uma porta específica de dentro do contêiner usando portas do 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 @-
Ou permitindo que o contêiner use as portas do host diretamente com --network=host (o que também pode proporcionar melhor desempenho de rede): 
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 @-
O usuário default do exemplo acima está disponível apenas para requisições via localhost

​
Volumes

Em geral, convém montar as seguintes pastas no contêiner para garantir a persistência:
  • /var/lib/clickhouse/ - pasta principal onde o ClickHouse armazena os dados
  • /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
Você também pode querer montar:
  • /etc/clickhouse-server/config.d/*.xml - arquivos com ajustes na configuração do servidor
  • /etc/clickhouse-server/users.d/*.xml - arquivos com ajustes nas configurações de usuário
  • /docker-entrypoint-initdb.d/ - pasta com scripts de inicialização do banco de dados (veja abaixo).

​
Capacidades do Linux

O ClickHouse tem algumas funcionalidades avançadas que exigem a ativação de várias capacidades do Linux Elas são opcionais e podem ser ativadas usando os seguintes argumentos de linha de comando do 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 obter mais informações, consulte “Configurando as capacidades CAP_IPC_LOCK e CAP_SYS_NICE no Docker”

​
Configuração

O contêiner expõe a porta 8123 para a interface HTTP e a porta 9000 para o cliente nativo. A configuração do ClickHouse é definida em um arquivo “config.xml” (documentação)

​
Inicie a instância do servidor com uma configuração 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

​
Inicie o servidor com um usuário personalizado

# $PWD/data/clickhouse deve existir e pertencer ao usuário atual
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
Ao usar a imagem com diretórios locais montados, provavelmente você vai querer especificar o usuário para manter a propriedade correta dos arquivos. Use o argumento --user e monte /var/lib/clickhouse e /var/log/clickhouse-server dentro do contêiner. Caso contrário, a imagem emitirá um erro e não iniciará.

​
Iniciar o servidor como root

Iniciar o servidor como root é útil nos casos em que o espaço de nomes do usuário está habilitado. Para fazer isso, execute: 
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

​
Como criar o banco de dados e o usuário padrão na inicialização

Às vezes, pode ser necessário criar um usuário (por padrão, é usado o usuário chamado default) e um banco de dados ao iniciar um contêiner. Você pode fazer isso usando as variáveis de ambiente CLICKHOUSE_DB, CLICKHOUSE_USER, CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT e 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

​
Gerenciando o usuário default

O usuário default tem o acesso de rede desabilitado por padrão caso CLICKHOUSE_USER, CLICKHOUSE_PASSWORD e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT não estejam definidos. Há uma forma de disponibilizar o usuário default de modo inseguro definindo a variável de ambiente CLICKHOUSE_SKIP_USER_SETUP como 1: 
docker run --rm -e CLICKHOUSE_SKIP_USER_SETUP=1 -p 9000:9000/tcp clickhouse/clickhouse-server

​
Como estender esta imagem

Para fazer inicializações adicionais em uma imagem derivada desta, adicione um ou mais scripts *.sql, *.sql.gz ou *.sh em /docker-entrypoint-initdb.d. Depois que o entrypoint chamar initdb, ele executará todos os arquivos *.sql, executará todos os scripts *.sh marcados como executáveis e fará o source de todos os scripts *.sh não executáveis encontrados nesse diretório para realizar inicializações adicionais antes de iniciar o serviço.
Os scripts em /docker-entrypoint-initdb.d são executados em ordem alfabética pelo nome do arquivo. Se seus scripts tiverem dependências entre si (por exemplo, um script que cria views precisa ser executado depois do script que cria as tabelas referenciadas), verifique se os nomes dos arquivos estão na ordem correta.
Além disso, você pode fornecer as variáveis de ambiente CLICKHOUSE_USER & CLICKHOUSE_PASSWORD, que serão usadas pelo clickhouse-client durante a inicialização. Por exemplo, para adicionar outro usuário e banco de dados, adicione o seguinte 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 modificação em 10 de junho de 2026