Skip to main content
Skip to main content
Edit this page

Install ClickHouse using Docker

The guide on Docker Hub is reproduced below for convenience. The Docker images available make use of the official ClickHouse deb packages.

Docker pull command:

Versions​

  • The latest tag points to the latest release of the latest stable branch.
  • Branch tags like 22.2 point to the latest release of the corresponding branch.
  • Full Version tags like 22.2.3 and 22.2.3.5 point to the corresponding release.
  • The tag head is built from the latest commit to the default branch.
  • Each tag has an optional -alpine suffix to reflect that it's built on top of alpine.

Compatibility​

  • The amd64 image requires support for SSE3 instructions. Virtually all x86 CPUs after 2005 support SSE3.
  • The arm64 image requires support for the ARMv8.2-A architecture and additionally the Load-Acquire RCpc register. The register is optional in version ARMv8.2-A and mandatory in ARMv8.3-A. Supported in Graviton >=2, Azure and GCP instances. Examples for unsupported devices are Raspberry Pi 4 (ARMv8.0-A) and Jetson AGX Xavier/Orin (ARMv8.2-A).
  • Since ClickHouse 24.11 Ubuntu images began using ubuntu:22.04 as its base image. It requires docker version >= 20.10.10 containing patch. As a workaround you could use docker run --security-opt seccomp=unconfined instead, however this has security implications.

How to use this image​

Start server instance​

By default, ClickHouse will be accessible only via the Docker network. See the networking section below.

By default, starting above server instance will be run as the default user without password.

Connect to it from a native client​

See ClickHouse client for more information about ClickHouse client.

Connect to it using curl​

See ClickHouse HTTP Interface for more information about the HTTP interface.

Stopping / removing the container​

Networking​

note

the predefined user default does not have the network access unless the password is set, see "How to create default database and user on starting" and "Managing default user" below

You can expose your ClickHouse running in docker by mapping a particular port from inside the container using host ports:

Or by allowing the container to use host ports directly using --network=host (also allows achieving better network performance):

note

The user default in the example above is available only for the localhost requests

Volumes​

Typically you may want to mount the following folders inside your container to achieve persistency:

  • /var/lib/clickhouse/ - main folder where ClickHouse stores the data
  • /var/log/clickhouse-server/ - logs

You may also want to mount:

  • /etc/clickhouse-server/config.d/*.xml - files with server configuration adjustments
  • /etc/clickhouse-server/users.d/*.xml - files with user settings adjustments
  • /docker-entrypoint-initdb.d/ - folder with database initialization scripts (see below).

Linux capabilities​

ClickHouse has some advanced functionality, which requires enabling several Linux capabilities

They are optional and can be enabled using the following docker command-line arguments:

For more information see "Configuring CAP_IPC_LOCK and CAP_SYS_NICE Capabilities in Docker"

Configuration​

The container exposes port 8123 for the HTTP interface and port 9000 for the native client.

ClickHouse configuration is represented with a file "config.xml" (documentation)

Start server instance with custom configuration​

Start server as custom user​

When you use the image with local directories mounted, you probably want to specify the user to maintain the proper file ownership. Use the --user argument and mount /var/lib/clickhouse and /var/log/clickhouse-server inside the container. Otherwise, the image will complain and not start.

Start server from root​

Starting the server from root is useful in cases where user namespace is enabled. To do so run:

How to create default database and user on start​

Sometimes you may want to create a user (user named default is used by default) and database on a container start. You can do it using environment variables CLICKHOUSE_DB, CLICKHOUSE_USER, CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT and CLICKHOUSE_PASSWORD:

Managing default user​

The user default has disabled network access by default in the case none of CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, or CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT are set.

There's a way to make default user insecurely available by setting environment variable CLICKHOUSE_SKIP_USER_SETUP to 1:

How to extend this image​

To perform additional initialization in an image derived from this one, add one or more *.sql, *.sql.gz, or *.sh scripts under /docker-entrypoint-initdb.d. After the entrypoint calls initdb, it will run any *.sql files, run any executable *.sh scripts, and source any non-executable *.sh scripts found in that directory to do further initialization before starting the service.
Also, you can provide environment variables CLICKHOUSE_USER & CLICKHOUSE_PASSWORD that will be used for clickhouse-client during initialization.

For example, to add another user and database, add the following to /docker-entrypoint-initdb.d/init-db.sh: