Docker로 ClickHouse 설치하기
Docker로 ClickHouse 설치하기 (Install ClickHouse using Docker)
ClickHouse 공식 Docker 이미지를 풀(pull)하고 컨테이너로 실행하는 방법을 안내합니다. 서버 시작, 연결, 네트워킹, 볼륨, 사용자 설정, 커스텀 구성까지 다룹니다.
출처: 문서
본문
Docker Hub의 가이드를 편의를 위해 아래에 재현합니다. 제공되는 Docker 이미지는 공식 ClickHouse deb 패키지를 사용합니다.
Docker pull 명령:
docker pull clickhouse/clickhouse-server
버전 (Versions)
latest태그는 최신 안정 브랜치의 최신 릴리스를 가리킵니다.22.2같은 브랜치 태그는 해당 브랜치의 최신 릴리스를 가리킵니다.22.2.3,22.2.3.5같은 전체 버전 태그는 해당 릴리스를 가리킵니다.head태그는 기본 브랜치의 최신 커밋으로 빌드됩니다.- 각 태그는
alpine위에 빌드되었음을 나타내는 선택적-alpine접미사를 가질 수 있습니다.
호환성 (Compatibility)
- amd64 이미지는 x86-64-v3 마이크로아키텍처 레벨(AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, XSAVE)을 지원해야 합니다. 2015년 이후의 거의 모든 x86 CPU가 x86-64-v3를 지원합니다.
- 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을 사용할 수 있지만 이는 보안상 영향이 있습니다.
이 이미지 사용 방법 (How to use this image)
서버 인스턴스 시작
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
네트워킹 (Networking)
사전 정의된 사용자 default는 비밀번호가 설정되지 않으면 네트워크 접근 권한이 없습니다. 아래 "기본 데이터베이스·사용자 시작 시 생성" 및 "default 사용자 관리"를 참고하세요.
호스트 포트를 사용해 컨테이너 내부에서 특정 포트를 매핑함으로써 docker에서 실행 중인 ClickHouse를 노출할 수 있습니다:
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 @-
위 예제의 default 사용자는 localhost 요청에만 사용할 수 있습니다.
볼륨 (Volumes)
일반적으로 영속성을 위해 컨테이너 내부에 다음 폴더를 마운트하고 싶을 것입니다:
/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 capabilities
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
자세한 내용은 "Configuring CAP_IPC_LOCK and CAP_SYS_NICE Capabilities in Docker"를 참고하세요.
구성 (Configuration)
컨테이너는 HTTP 인터페이스용 포트 8123과 네이티브 클라이언트용 포트 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가 존재하고 현재 사용자 소유여야 합니다
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로 서버를 시작하는 것은 user namespace가 활성화된 경우 유용합니다. 그러려면:
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 사용자 관리
CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT 중 어느 것도 설정되지 않은 경우 default 사용자는 기본적으로 네트워크 접근이 비활성화되어 있습니다.
환경 변수 CLICKHOUSE_SKIP_USER_SETUP을 1로 설정하면 default 사용자를 안전하지 않게 사용 가능하게 하는 방법이 있습니다:
docker run --rm -e CLICKHOUSE_SKIP_USER_SETUP=1 -p 9000:9000/tcp clickhouse/clickhouse-server
이 이미지 확장 방법 (How to extend this image)
이 이미지에서 파생된 이미지에서 추가 초기화를 수행하려면 /docker-entrypoint-initdb.d 아래에 하나 이상의 *.sql, *.sql.gz 또는 *.sh 스크립트를 추가하세요. 엔트리포인트가 initdb를 호출한 후 서비스를 시작하기 전에 해당 디렉터리에서 발견된 *.sql 파일을 실행하고, 실행 가능한 *.sh 스크립트를 실행하며, 실행 불가능한 *.sh 스크립트를 소싱해 추가 초기화를 수행합니다.
/docker-entrypoint-initdb.d 아래의 스크립트는 파일 이름 기준 알파벳순으로 실행됩니다. 스크립트가 서로 의존 관계가 있다면(예: 뷰를 만드는 스크립트는 참조하는 테이블을 만드는 스크립트 다음에 실행되어야 함) 파일 이름이 올바른 순서로 정렬되는지 확인하세요.
또한 초기화 중 clickhouse-client에 사용될 환경 변수 CLICKHOUSE_USER & CLICKHOUSE_PASSWORD를 제공할 수 있습니다.
예를 들어 사용자와 데이터베이스를 추가하려면 /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