> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Install ClickHouse on Debian/Ubuntu Linux
# Install ClickHouse using Docker
# Install ClickHouse using Docker
The guide on [Docker Hub](https://hub.docker.com/r/clickhouse/clickhouse-server/)
is reproduced below for convenience. The Docker images available make use of
the official ClickHouse deb packages.
Docker pull command:
```bash theme={null}
docker pull clickhouse/clickhouse-server
```
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](https://en.wikipedia.org/wiki/SSE3).
Virtually all x86 CPUs after 2005 support SSE3.
* The arm64 image requires support for the [ARMv8.2-A architecture](https://en.wikipedia.org/wiki/AArch64#ARMv8.2-A) and
additionally the Load-Acquire RCpc register. The register is optional in version ARMv8.2-A and mandatory in
[ARMv8.3-A](https://en.wikipedia.org/wiki/AArch64#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](https://github.com/moby/moby/commit/977283509f75303bc6612665a04abf76ff1d2468). 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
```bash theme={null}
docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
```
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
```bash theme={null}
docker run -it --rm --network=container:some-clickhouse-server --entrypoint clickhouse-client clickhouse/clickhouse-server
# OR
docker exec -it some-clickhouse-server clickhouse-client
```
See [ClickHouse client](/concepts/features/interfaces/cli) for more information about ClickHouse client.
Connect to it using curl
```bash theme={null}
echo "SELECT 'Hello, ClickHouse!'" | docker run -i --rm --network=container:some-clickhouse-server buildpack-deps:curl curl 'http://localhost:8123/?query=' -s --data-binary @-
```
See [ClickHouse HTTP Interface](/concepts/features/interfaces/http) for more information about the HTTP interface.
Stopping / removing the container
```bash theme={null}
docker stop some-clickhouse-server
docker rm some-clickhouse-server
```
Networking
the predefined user `default` doesn't 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](https://docs.docker.com/config/containers/container-networking/)
from inside the container using host ports:
```bash theme={null}
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 @-
```
Or by allowing the container to use [host ports directly](https://docs.docker.com/network/host/) using `--network=host`
(also allows achieving better network performance):
```bash theme={null}
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 @-
```
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
```bash theme={null}
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
```
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](https://man7.org/linux/man-pages/man7/capabilities.7.html)
They're optional and can be enabled using the following [docker command-line arguments](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities):
```bash theme={null}
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
```
For more information see ["Configuring CAP\_IPC\_LOCK and CAP\_SYS\_NICE Capabilities in Docker"](/resources/support-center/knowledge-base/troubleshooting/configure-cap-ipc-lock-and-cap-sys-nice-in-docker)
Configuration
The container exposes port 8123 for the [HTTP interface](/concepts/features/interfaces/http) and port 9000 for the [native client](/concepts/features/interfaces/tcp).
ClickHouse configuration is represented with a file "config.xml" ([documentation](/concepts/features/configuration/server-config/configuration-files))
Start server instance with custom configuration
```bash theme={null}
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
```
Start server as custom user
```bash theme={null}
# $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
```
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:
```bash theme={null}
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
```
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`:
```bash theme={null}
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
```
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:
```bash theme={null}
docker run --rm -e CLICKHOUSE_SKIP_USER_SETUP=1 -p 9000:9000/tcp clickhouse/clickhouse-server
```
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.
Scripts under `/docker-entrypoint-initdb.d` are executed in **alphabetical order** by filename. If your scripts have dependencies on each other (for example, a script that creates views must run after the script that creates the referenced tables), ensure your filenames sort in the correct order.
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`:
```bash theme={null}
#!/bin/bash
set -e
clickhouse client -n <<-EOSQL
CREATE DATABASE docker;
CREATE TABLE docker.docker (x Int32) ENGINE = MergeTree
ORDER BY ();
EOSQL
```