메인 콘텐츠로 건너뛰기

​
Docker를 사용해 ClickHouse 설치

편의를 위해 Docker Hub의 가이드를 아래에 그대로 옮겼습니다. 제공되는 Docker 이미지는 공식 ClickHouse deb 패키지를 사용합니다. Docker pull 명령: 
docker pull clickhouse/clickhouse-server

​
버전

  • latest 태그는 최신 안정 브랜치의 최신 릴리스를 가리킵니다.
  • 22.2와 같은 브랜치 태그는 해당 브랜치의 최신 릴리스를 가리킵니다.
  • 22.2.3 및 22.2.3.5와 같은 전체 버전 태그는 해당 릴리스를 가리킵니다.
  • head 태그는 기본 브랜치의 최신 커밋을 기준으로 빌드됩니다.
  • 각 태그에는 alpine 기반으로 빌드되었음을 나타내는 선택적 -alpine 접미사를 추가할 수 있습니다.

​
호환성

  • amd64 이미지는 SSE3 명령어 지원이 필요합니다. 2005년 이후의 거의 모든 x86 CPU는 SSE3를 지원합니다.
  • 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를 사용합니다. 이를 위해서는 patch가 포함된 20.10.10 이상의 docker 버전이 필요합니다. 우회 방법으로 docker run --security-opt seccomp=unconfined를 대신 사용할 수 있지만, 보안상 영향이 있을 수 있습니다.

​
이 이미지 사용 방법

​
서버 인스턴스 시작하기

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
# 또는
docker exec -it some-clickhouse-server clickhouse-client
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 @-
ClickHouse HTTP Interface에서 HTTP 인터페이스에 관한 자세한 내용을 확인하십시오.

​
컨테이너 중지 및 제거

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

​
네트워킹

미리 정의된 사용자 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에서의 요청에만 사용할 수 있습니다

​
볼륨

일반적으로 영구 저장을 위해 다음 폴더를 컨테이너 내부에 마운트합니다:
  • /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 capability

ClickHouse에는 몇 가지 고급 기능이 있으며, 이를 사용하려면 여러 Linux capability를 활성화해야 합니다. 이 기능은 선택 사항이며, 다음 docker command-line arguments를 사용해 활성화할 수 있습니다: 
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
자세한 내용은 “Docker에서 CAP_IPC_LOCK 및 CAP_SYS_NICE capability 구성하기”을 참조하십시오.

​
구성

컨테이너는 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를 컨테이너 내부에 마운트하십시오. 그렇지 않으면 이미지가 오류를 내고 시작되지 않습니다.

​
루트 권한으로 서버 시작

사용자 네임스페이스가 활성화된 경우 루트 권한으로 서버를 시작하는 것이 유용합니다. 이렇게 하려면 다음을 실행하세요: 
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

​
이 이미지를 확장하는 방법

이 이미지에서 파생된 이미지에서 추가 초기화를 수행하려면 /docker-entrypoint-initdb.d 아래에 *.sql, *.sql.gz, 또는 *.sh 스크립트를 하나 이상 추가하십시오. entrypoint가 initdb를 호출한 후 서비스가 시작되기 전에 추가 초기화를 수행하기 위해, 해당 디렉터리에서 찾은 모든 *.sql 파일을 실행하고, 실행 가능한 *.sh 스크립트를 실행하며, 실행 가능하지 않은 *.sh 스크립트는 source합니다.
/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
마지막 수정일 2026년 6월 10일