diff --git a/docs/reference/setup/install/docker.asciidoc b/docs/reference/setup/install/docker.asciidoc
index 28867f04ed795..328916a11be16 100644
--- a/docs/reference/setup/install/docker.asciidoc
+++ b/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
diff --git a/docs/reference/setup/jvm-options.asciidoc b/docs/reference/setup/jvm-options.asciidoc
index bd39b6781dda4..61c24fc1e1b21 100644
--- a/docs/reference/setup/jvm-options.asciidoc
+++ b/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: