chia7712 commented on code in PR #23819:
URL: https://github.com/apache/kafka/pull/23819#discussion_r4331373689


##########
docs/getting-started/docker.md:
##########
@@ -73,8 +73,93 @@ $ docker run -p 9092:9092 apache/kafka-native:4.4.0
 
 ### SASL and SSL
 
-The native image supports SASL authentication since 4.4.0; earlier native 
images do not. Docker Compose examples for SASL and SSL, which work with both 
the JVM and the native image, are described in the [usage 
guide](https://github.com/apache/kafka/blob/trunk/docker/examples/README.md).
+The native image supports SASL authentication since 4.4.0; earlier native 
images do not. See [Running in SASL mode](#running-in-sasl-mode) and [Running 
in SSL mode](#running-in-ssl-mode) below; both apply to the JVM and the native 
image.
 
 ## Usage guide
 
-Detailed instructions for using the Docker image are mentioned 
[here](https://github.com/apache/kafka/blob/trunk/docker/examples/README.md). 
+The Kafka server in the Docker container can be configured in the following 
ways:
+
+- Default configs
+- File input
+- Environment variables
+
+### Installation preparation
+
+Note that the Docker version **must be >= 20.10.4**.
+
+Earlier Docker versions may cause permission errors when running the Kafka 
container, as they do not correctly set directory permissions when creating 
container paths like `/opt/kafka/config`.
+
+With an earlier version, you may encounter the following error during 
container startup:
+
+```text
+===> User
+uid=1000(appuser) gid=1000(appuser) groups=1000(appuser)
+===> Setting default values of environment variables if not already set.
+===> Configuring …
+Running in KRaft mode…
+/opt/kafka/config/ file not writable
+```
+
+To avoid this, **please upgrade Docker to 20.10.4 or later**.
+
+### Running on default configs
+
+If no user provided configuration (file input or environment variables) is 
passed to the Docker container, the default KRaft configuration for a single 
combined-mode node will be used. This default configuration is packaged in the 
Kafka tarball.
+
+### Using an input file for providing configs
+
+- This method requires users to provide the path to a local folder which 
contains the Kafka property files and mount it to the Docker container using a 
Docker volume.
+- It replaces the default KRaft configuration file present in the Docker 
container.
+- The following command can be used to mount the folder containing the 
property files:
+
+```bash
+$ docker run --volume /path/to/property/folder:/mnt/shared/config -p 9092:9092 
apache/kafka:latest
+```
+
+- Property files will only be read by the Docker container.
+
+### Using environment variables
+
+When using environment variables, you need to set all properties required to 
start the KRaft node. Therefore, the recommended way to use environment 
variables is via Docker Compose, which allows users to set all the properties 
that are needed. It is also possible to use the input file to have a common set 
of configurations, and then override specific node properties using environment 
variables.
+
+- A Kafka property defined via an environment variable will override the value 
of that property defined in the user provided property file.
+- If properties are provided via environment variables only, all required 
properties must be specified.
+- The following rules must be used to construct the environment variable key 
name:
+  - Replace `.` with `_`
+  - Replace `_` with `__` (double underscore)
+  - Replace `-` with `___` (triple underscore)
+  - Prefix the result with `KAFKA_`
+  - Examples:
+    - For `abc.def`, use `KAFKA_ABC_DEF`
+    - For `abc-def`, use `KAFKA_ABC___DEF`
+    - For `abc_def`, use `KAFKA_ABC__DEF`
+- To provide configs to log4j property files, the following points should be 
considered:
+  - log4j properties provided via environment variables will be appended to 
the default properties file (log4j properties files bundled with Kafka).
+  - `KAFKA_LOG4J_ROOT_LOGLEVEL` can be provided to set the value of 
`log4j.rootLogger` in `log4j2.yaml` and `tools-log4j2.yaml`.
+  - log4j loggers can be added to `log4j2.yaml` by setting them in the 
`KAFKA_LOG4J_LOGGERS` environment variable as a single comma separated string.
+    - Example: assuming that 
`KAFKA_LOG4J_LOGGERS='property1=value1,property2=value2'` is provided to the 
Docker container, `log4j.logger.property1=value1` and 
`log4j.logger.property2=value2` will be added to the `log4j2.yaml` file inside 
the Docker container.

Review Comment:
   I believe this description is out-of-date, and it could be a follow-up. see 
KafkaDockerWrapper



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to