docs: Revise docs for the OVERRIDE_HOSTNAME ENV (#4492)

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file. The format
 
 - **Environment Variables:**
   - [ENV can be declared with a `__FILE` suffix](https://docker-mailserver.github.io/docker-mailserver/v15.1/config/environment/) to read a value from a file during initial DMS setup scripts ([#4359](https://github.com/docker-mailserver/docker-mailserver/pull/4359))
+  - Improved docs for the ENV `OVERRIDE_HOSTNAME` ([#4492](https://github.com/docker-mailserver/docker-mailserver/pull/4492))
 - **Internal:**
   - [`DMS_CONFIG_POLL`](https://docker-mailserver.github.io/docker-mailserver/v15.0/config/environment/#dms_config_poll) supports adjusting the polling rate (seconds) for the change detection service `check-for-changes.sh` ([#4450](https://github.com/docker-mailserver/docker-mailserver/pull/4450))
 

docs/content/config/environment.md

@@ -14,11 +14,23 @@ title: Environment Variables
 
 ##### OVERRIDE_HOSTNAME
 
-If you can't set your hostname (_eg: you're in a container platform that doesn't let you_) specify it via this environment variable. It will have priority over `docker run --hostname`, or the equivalent `hostname:` field in `compose.yaml`.
+If you cannot set your DMS FQDN as your hostname (_eg: you're in a container runtime lacks the equivalent of Docker's `--hostname`_), specify it via this environment variable.
 
-- **empty** => Uses the `hostname -f` command to get canonical hostname for DMS to use.
+- **empty** => Internally uses the `hostname --fqdn` command to get the canonical hostname assigned to the DMS container.
 - => Specify an FQDN (fully-qualified domain name) to serve mail for. The hostname is required for DMS to function correctly.
 
+!!! info
+
+    `OVERRIDE_HOSTNAME` is checked early during DMS container setup. When set it will be preferred over querying the containers hostname via the `hostname --fqdn` command (_configured via `docker run --hostname` or the equivalent `hostname:` field in `compose.yaml`_).
+
+!!! warning "Compatibility may differ"
+
+    `OVERRIDE_HOSTNAME` is not a complete replacement for adjusting the containers configured hostname. It is a best effort workaround for supporting deployment environments like Kubernetes or when using Docker with `--network=host`.
+
+    Typically this feature is only useful when software supports configuring a specific hostname to use, instead of a default fallback that infers the hostname (such as retrieving the hostname via libc / NSS). [Fetchmail is known to be incompatible][gh--issue::hostname-compatibility] with this ENV, requiring manual workarounds.
+
+    Compatibility differences are being [tracked here][gh-issue::dms-fqdn] as they become known.
+
 ##### LOG_LEVEL
 
 Set the log level for DMS. This is mostly relevant for container startup scripts and change detection event feedback.
@@ -1183,3 +1195,5 @@ Provide the credentials to use with `RELAY_HOST` or `DEFAULT_RELAY_HOST`.
 [postfix-config::relayhost_maps]: https://www.postfix.org/postconf.5.html#sender_dependent_relayhost_maps
 [postfix-config::sasl_passwd]: https://www.postfix.org/postconf.5.html#smtp_sasl_password_maps
 [gh-issue::tls-legacy-workaround]: https://github.com/docker-mailserver/docker-mailserver/pull/2945#issuecomment-1949907964
+[gh-issue::hostname-compatibility]: https://github.com/docker-mailserver/docker-mailserver-helm/issues/168#issuecomment-2911782106
+[gh-issue::dms-fqdn]: https://github.com/docker-mailserver/docker-mailserver/issues/3520#issuecomment-1700191973

mailserver.env

@@ -9,13 +9,13 @@
 # --- General Section ---------------------------
 # -----------------------------------------------
 
-# empty => uses the `hostname` command to get the mail server's canonical hostname
-# => Specify a fully-qualified domainname to serve mail for.  This is used for many of the config features so if you can't set your hostname (e.g. you're in a container platform that doesn't let you) specify it in this environment variable.
+# **empty** => Internally uses the `hostname --fqdn` command to get the canonical hostname assigned to the DMS container.
+# => Specify an FQDN (fully-qualified domain name) to serve mail for. The hostname is required for DMS to function correctly
+#
+# **WARNING**: Setting OVERRIDE_HOSTNAME can have difficult to predict side effects:
+# https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/#override_hostname
 OVERRIDE_HOSTNAME=
 
-# REMOVED in version v11.0.0! Use LOG_LEVEL instead.
-DMS_DEBUG=0
-
 # Set the log level for DMS.
 # This is mostly relevant for container startup scripts and change detection event feedback.
 #