From bca41bb7fd1275ed989113ef2f729e4f4fa89eac Mon Sep 17 00:00:00 2001
From: filimonov <1549571+filimonov@users.noreply.github.com>
Date: Mon, 14 Dec 2020 16:50:48 +0100
Subject: [PATCH] Update README.md

---
 docker/server/README.md | 63 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/docker/server/README.md b/docker/server/README.md
index 4fc8e8cf344..cbb70b6f11a 100644
--- a/docker/server/README.md
+++ b/docker/server/README.md
@@ -12,9 +12,11 @@ For more information and documentation see https://clickhouse.yandex/.
 
 ### start server instance
 ```bash
-$ docker run -d -p 8123:8123 --name some-clickhouse-server --ulimit nofile=262144:262144 yandex/clickhouse-server
+$ docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 yandex/clickhouse-server
 ```
 
+By default ClickHouse will be accessible only via docker network. See the [networking section below](#networking).
+
 ### connect to it from a native client
 ```bash
 $ docker run -it --rm --link some-clickhouse-server:clickhouse-server yandex/clickhouse-client --host clickhouse-server
@@ -25,10 +27,67 @@ More information about [ClickHouse client](https://clickhouse.yandex/docs/en/int
 ### connect to it using curl
 
 ```bash
-$ echo 'SELECT 1' | curl 'http://localhost:8123/?query=' --data-binary @-
+echo "SELECT 'Hello, ClickHouse!'" | docker run -i --rm --link some-clickhouse-server:clickhouse-server curlimages/curl 'http://clickhouse-server:8123/?query=' -s --data-binary @-
 ```
 More information about [ClickHouse HTTP Interface](https://clickhouse.tech/docs/en/interfaces/http/).
 
+### stopping the containter
+
+```bash
+$ docker stop some-clickhouse-server
+$ docker rm some-clickhouse-server
+```
+
+### networking
+
+You can expose you ClickHouse running in docker by [mapping particular port](https://docs.docker.com/config/containers/container-networking/) from inside container to a host ports:
+
+```bash
+$ docker run -d -p 18123:8123 -p19000:9000 --name some-clickhouse-server --ulimit nofile=262144:262144 yandex/clickhouse-server
+$ echo 'SELECT version()' | curl 'http://localhost:18123/' --data-binary @-
+20.12.3.3
+```
+
+or by allowing container to use [host ports directly](https://docs.docker.com/network/host/) using `--network=host` (also allow to archive better network performance):
+
+```bash
+$ docker run -d --network=host --name some-clickhouse-server --ulimit nofile=262144:262144 yandex/clickhouse-server
+$ echo 'SELECT version()' | curl 'http://localhost:8123/' --data-binary @-
+20.12.3.3
+```
+
+### Volumes 
+
+Typically you may want to mount the following folders inside your container to archieve persistency:
+
+* `/var/lib/clickhouse/` - main folder where ClickHouse stores the data
+* `/val/log/clickhouse-server/` - logs
+
+```bash
+$ docker run -d \
+	-v $(realpath ./ch_data):/var/lib/clickhouse/ \
+	-v $(realpath ./ch_logs):/var/log/clickhouse-server/ \
+	--name some-clickhouse-server --ulimit nofile=262144:262144 yandex/clickhouse-server
+```
+
+You may also want to mount:
+
+* `/etc/clickhouse-server/config.d/*.xml` - files with server configuration adjustmenets
+* `/etc/clickhouse-server/usert.d/*.xml` - files with use settings adjustmenets
+* `/docker-entrypoint-initdb.d/` - folder with database initialization scripts (see below).
+
+### Linux capabilities 
+
+ClickHouse has some anvanced functionality which requite enabling several [linux capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html).
+
+It is optional and can be enabled using the following [docker command line agruments](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities):
+
+```bash
+$ docker run -d \
+	--cap-add=SYS_NICE --cap-add=NET_ADMIN --cap-add=IPC_LOCK \
+	--name some-clickhouse-server --ulimit nofile=262144:262144 yandex/clickhouse-server
+```
+
 ## Configuration
 
 Container exposes 8123 port for [HTTP interface](https://clickhouse.yandex/docs/en/interfaces/http_interface/) and 9000 port for [native client](https://clickhouse.yandex/docs/en/interfaces/tcp/).