Skip to content

Commit 007e320

Browse files
FelixoidFelixoid
authored
Initial commitment of documentation for clickhouse official image (#2397)
1 parent 8c29fb9 commit 007e320

File tree

7 files changed

+214
-0
lines changed

7 files changed

+214
-0
lines changed

‎clickhouse/README-short.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
ClickHouse is the fastest and most resource efficient OSS database for real-time apps and analytics.

‎clickhouse/content.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# ClickHouse Server Docker Image
2+
3+
## What is ClickHouse?
4+
5+
%%LOGO%%
6+
7+
ClickHouse is an open-source column-oriented DBMS (columnar database management system) for online analytical processing (OLAP) that allows users to generate analytical reports using SQL queries in real-time.
8+
9+
ClickHouse works 100-1000x faster than traditional database management systems, and processes hundreds of millions to over a billion rows and tens of gigabytes of data per server per second. With a widespread user base around the globe, the technology has received praise for its reliability, ease of use, and fault tolerance.
10+
11+
For more information and documentation see https://clickhouse.com/.
12+
13+
### Compatibility
14+
15+
- The amd64 image requires support for [SSE3 instructions](https://en.wikipedia.org/wiki/SSE3). Virtually all x86 CPUs after 2005 support SSE3.
16+
- 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).
17+
- Since the Clickhouse 24.11 Ubuntu images started 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 that has security implications.
18+
19+
## How to use this image
20+
21+
### start server instance
22+
23+
```bash
24+
docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 %%IMAGE%%
25+
```
26+
27+
By default, ClickHouse will be accessible only via the Docker network. See the **networking** section below.
28+
29+
By default, starting above server instance will be run as the `default` user without password.
30+
31+
### connect to it from a native client
32+
33+
```bash
34+
docker run -it --rm --link some-clickhouse-server:clickhouse-server --entrypoint clickhouse-client %%IMAGE%% --host clickhouse-server
35+
# OR
36+
docker exec -it some-clickhouse-server clickhouse-client
37+
```
38+
39+
More information about the [ClickHouse client](https://clickhouse.com/docs/en/interfaces/cli/).
40+
41+
### connect to it using curl
42+
43+
```bash
44+
echo "SELECT 'Hello, ClickHouse!'" | docker run -i --rm --link some-clickhouse-server:clickhouse-server buildpack-deps:curl curl 'http://clickhouse-server:8123/?query=' -s --data-binary @-
45+
```
46+
47+
More information about the [ClickHouse HTTP Interface](https://clickhouse.com/docs/en/interfaces/http/).
48+
49+
### stopping / removing the container
50+
51+
```bash
52+
docker stop some-clickhouse-server
53+
docker rm some-clickhouse-server
54+
```
55+
56+
### networking
57+
58+
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:
59+
60+
```bash
61+
docker run -d -p 18123:8123 -p19000:9000 --name some-clickhouse-server --ulimit nofile=262144:262144 %%IMAGE%%
62+
echo 'SELECT version()' | curl 'http://localhost:18123/' --data-binary @-
63+
```
64+
65+
`22.6.3.35`
66+
67+
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):
68+
69+
```bash
70+
docker run -d --network=host --name some-clickhouse-server --ulimit nofile=262144:262144 %%IMAGE%%
71+
echo 'SELECT version()' | curl 'http://localhost:8123/' --data-binary @-
72+
```
73+
74+
`22.6.3.35`
75+
76+
### Volumes
77+
78+
Typically you may want to mount the following folders inside your container to achieve persistency:
79+
80+
- `/var/lib/clickhouse/` - main folder where ClickHouse stores the data
81+
- `/var/log/clickhouse-server/` - logs
82+
83+
```bash
84+
docker run -d \
85+
-v "$PWD/ch_data:/var/lib/clickhouse/" \
86+
-v "$PWD/ch_logs:/var/log/clickhouse-server/" \
87+
--name some-clickhouse-server --ulimit nofile=262144:262144 %%IMAGE%%
88+
```
89+
90+
You may also want to mount:
91+
92+
- `/etc/clickhouse-server/config.d/*.xml` - files with server configuration adjustments
93+
- `/etc/clickhouse-server/users.d/*.xml` - files with user settings adjustments
94+
- `/docker-entrypoint-initdb.d/` - folder with database initialization scripts (see below).
95+
96+
### Linux capabilities
97+
98+
ClickHouse has some advanced functionality, which requires enabling several [Linux capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html).
99+
100+
They are optional and can be enabled using the following [docker command-line arguments](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities):
101+
102+
```bash
103+
docker run -d \
104+
--cap-add=SYS_NICE --cap-add=NET_ADMIN --cap-add=IPC_LOCK \
105+
--name some-clickhouse-server --ulimit nofile=262144:262144 %%IMAGE%%
106+
```
107+
108+
Read more in [knowledge base](https://clickhouse.com/docs/knowledgebase/configure_cap_ipc_lock_and_cap_sys_nice_in_docker).
109+
110+
## Configuration
111+
112+
The container exposes port 8123 for the [HTTP interface](https://clickhouse.com/docs/en/interfaces/http_interface/) and port 9000 for the [native client](https://clickhouse.com/docs/en/interfaces/tcp/).
113+
114+
ClickHouse configuration is represented with a file "config.xml" ([documentation](https://clickhouse.com/docs/en/operations/configuration_files/))
115+
116+
### Start server instance with custom configuration
117+
118+
```bash
119+
docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 -v /path/to/your/config.xml:/etc/clickhouse-server/config.xml %%IMAGE%%
120+
```
121+
122+
### Start server as custom user
123+
124+
```bash
125+
# $PWD/data/clickhouse should exist and be owned by current user
126+
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" %%IMAGE%%
127+
```
128+
129+
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.
130+
131+
### Start server from root (useful in case of enabled user namespace)
132+
133+
```bash
134+
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" %%IMAGE%%
135+
```
136+
137+
### How to create default database and user on starting
138+
139+
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`:
140+
141+
```bash
142+
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 %%IMAGE%%
143+
```
144+
145+
## How to extend this image
146+
147+
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.
148+
Also, you can provide environment variables `CLICKHOUSE_USER` & `CLICKHOUSE_PASSWORD` that will be used for clickhouse-client during initialization.
149+
150+
For example, to add an additional user and database, add the following to `/docker-entrypoint-initdb.d/init-db.sh`:
151+
152+
```bash
153+
#!/bin/bash
154+
set -e
155+
156+
clickhouse client -n <<-EOSQL
157+
CREATE DATABASE docker;
158+
CREATE TABLE docker.docker (x Int32) ENGINE = Log;
159+
EOSQL
160+
```

‎clickhouse/github-repo

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
https://github.com/ClickHouse/ClickHouse

‎clickhouse/license.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
View [license information](https://github.com/ClickHouse/ClickHouse/blob/master/LICENSE) for the software contained in this image.

‎clickhouse/logo.svg

Lines changed: 43 additions & 0 deletions
Loading

‎clickhouse/maintainer.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
[ClickHouse Inc.](%%GITHUB-REPO%%)

‎clickhouse/metadata.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"hub": {
3+
"categories": [
4+
"databases-and-storage"
5+
]
6+
}
7+
}

0 commit comments

Comments
 (0)