Instale o ClickHouse usando o Docker

Instale o ClickHouse no Debian/Ubuntu Linux

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 recente.
• 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 a partir do commit mais recente na branch padrão.
• Cada tag tem um sufixo opcional -alpine para indicar que foi construída com base em alpine.

​

Compatibilidade

• A imagem amd64 requer suporte a instruções SSE3. Praticamente todas as CPUs x86 posteriores a 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 em ARMv8.3-A. Há suporte em instâncias Graviton >=2, Azure e GCP. Exemplos de dispositivos sem suporte são Raspberry Pi 4 (ARMv8.0-A) e Jetson AGX Xavier/Orin (ARMv8.2-A).
• Desde o ClickHouse 24.11, as imagens do Ubuntu passaram a usar ubuntu:22.04 como imagem base. Isso requer o Docker >= 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 acima será executada como o usuário default, sem senha.

​

Conecte-se usando um cliente nativo

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

Consulte ClickHouse client para mais informações sobre o cliente ClickHouse.

​

Conecte-se a ele com 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.

​

Parar / remover o contêiner

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

​

Rede

o usuário predefinido default não tem acesso à rede, a menos que uma senha seja definida. Veja “Como criar o banco de dados padrão e o usuário na inicialização” e “Gerenciando o usuário default” abaixo.

Você pode expor sua instância do ClickHouse em execução no Docker mapeando uma porta específica de dentro do contêiner para 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 (também permite obter 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 no exemplo acima está disponível apenas para requisições feitas a partir de localhost

​

Volumes

Em geral, convém montar as seguintes pastas dentro do seu contêiner para garantir a persistência:

• /var/lib/clickhouse/ - pasta principal em que 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

Talvez você também queira montar:

• /etc/clickhouse-server/config.d/*.xml - arquivos com ajustes na configuração do servidor
• /etc/clickhouse-server/users.d/*.xml - arquivos com ajustes na configuração do 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 habilitação de várias capacidades do Linux

Elas são opcionais e podem ser habilitadas com 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 mais informações, consulte “Como configurar 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)

​

Iniciar instância do servidor com 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

​

Iniciar o servidor como um usuário personalizado

# $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

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 apresentará erro e não iniciará.

​

Iniciar o servidor como root

Iniciar o servidor como root é útil quando o namespace de 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 padrão e o usuário na inicialização

Às vezes, pode ser necessário criar um usuário (o usuário chamado default é usado por padrão) 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 à rede desabilitado por padrão caso nenhuma das variáveis CLICKHOUSE_USER, CLICKHOUSE_PASSWORD ou CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT esteja definida.

Há uma forma de disponibilizar o usuário default de maneira insegura 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 realizar uma inicialização adicional 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 executáveis e carregará todos os scripts *.sh não executáveis encontrados nesse diretório para realizar etapas adicionais de inicialização 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 os 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), garanta que os nomes dos arquivos fiquem 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 outro 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