Clarify use of ES_JAVA_OPTS and Docker (#51867)

Closes #51626. Tweak the documentation around configuring the heap size
when using Docker, to state that:

- using `ES_JAVA_OPTS` is the preferred method
- Any `ES_JAVA_OPTS` overrides the defaults in `jvm.options`
- It's possible to bind-mount a custom `jvm.options`

Author: pugnascotia

docs/reference/setup/install/docker.asciidoc

@@ -263,15 +263,25 @@ TCP ports 9200 and 9300. For production clusters, randomizing the
 published ports with `--publish-all` is recommended,
 unless you are pinning one container per host.
 
+[[docker-set-heap-size]]
 ===== Set the heap size
 
 Use the `ES_JAVA_OPTS` environment variable to set the heap size.
-For example, to use 16GB, specify `-e ES_JAVA_OPTS="-Xms16g -Xmx16g"` with `docker run`.
+For example, to use 16GB, specify `-e ES_JAVA_OPTS="-Xms16g -Xmx16g"` with
+`docker run`. Note that while the default configuration file `jvm.options`
+sets a default heap of 1GB, any value you set in `ES_JAVA_OPTS` will
+override it.
 
 IMPORTANT: You must <<heap-size,configure the heap size>> even if you are
 https://docs.docker.com/config/containers/resource_constraints/#limit-a-containers-access-to-memory[limiting
 memory access] to the container.
 
+While setting the heap size via an environment variable is the recommended
+method, you can also configure this by bind-mounting your own `jvm.options`
+file under `/usr/share/elasticsearch/config/`. The file that {es} provides
+contains some important settings, so you should start by taking a copy of
+`jvm.options` from an {es} container and editing it as you require.
+
 ===== Pin deployments to a specific image version
 
 Pin your deployments to a specific version of the {es} Docker image. For

docs/reference/setup/jvm-options.asciidoc

@@ -11,6 +11,10 @@ file is `config/jvm.options` (when installing from the tar or zip distributions)
 and `/etc/elasticsearch/jvm.options` (when installing from the Debian or RPM
 packages).
 
+NOTE: If you are using the <<docker,Docker distribution of {es}>>, we
+recommend that you <<docker-set-heap-size,set the heap size using the
+`ES_JAVA_OPTS` environment variable>>.
+
 This file contains a line-delimited list of JVM arguments following
 a special syntax: