From 01689ab788022097e79d80979303e206a5d48f24 Mon Sep 17 00:00:00 2001
From: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
Date: Mon, 4 Dec 2023 11:22:43 +1300
Subject: [PATCH] docs: Troubleshooting - Bare domain misconfiguration (#3680)

---
 CHANGELOG.md                     |  8 +++++++-
 docs/content/config/debugging.md | 11 +++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e6faa74a..8ecfbe55 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,13 @@ All notable changes to this project will be documented in this file. The format
 
 ### Added
 
-- command (`run-local-instance`) to test a version of DMS that was built locally to test changes
+- **Tests:**
+  - You can now use `make run-local-instance` to run a DMS image that was built locally to test changes ([#3663](https://github.com/docker-mailserver/docker-mailserver/pull/3663))
+
+### Updates
+
+- **Documentation:**
+  - Raise awareness in the troubleshooting page for a common misconfiguration when deviating from our advice by using a bare domain ([#3680](https://github.com/docker-mailserver/docker-mailserver/pull/3680))
 
 ### Fixed
 
diff --git a/docs/content/config/debugging.md b/docs/content/config/debugging.md
index d1e29376..9c3bebb5 100644
--- a/docs/content/config/debugging.md
+++ b/docs/content/config/debugging.md
@@ -46,6 +46,15 @@ Some service providers block outbound traffic on port 25. Common hosting provide
 
 These links may advise how the provider can unblock the port through additional services offered, or via a support ticket request.
 
+### Mail sent to DMS does not get delivered to user
+
+Common logs related to this are:
+
+- `warning: do not list domain domain.fr in BOTH mydestination and virtual_mailbox_domains`
+- `Recipient address rejected: User unknown in local recipient table`
+
+If your logs look like this, you likely have [assigned the same FQDN to the DMS `hostname` and your mail accounts][gh-issues::dms-fqdn-misconfigured] which is not supported by default. You can either adjust your DMS `hostname` or follow [this FAQ advice][docs::faq-bare-domain]
+
 ## Steps for Debugging DMS
 
 1. **Increase log verbosity**: Very helpful for troubleshooting problems during container startup. Set the environment variable [`LOG_LEVEL`][docs-environment-log-level] to `debug` or `trace`.
@@ -109,12 +118,14 @@ This could be from outdated software, or running a system that isn't able to pro
 
 [docs-environment-log-level]: ./environment.md#log_level
 [docs-faq]: ../faq.md
+[docs::faq-bare-domain]: ../faq.md#can-i-use-a-nakedbare-domain-ie-no-hostname
 [docs-ipv6]: ./advanced/ipv6.md
 [docs-introduction]: ../introduction.md
 [docs-rootless-portdriver]: ./security/fail2ban.md#running-inside-a-rootless-container
 [docs-usage]: ../usage.md
 
 [gh-issues]: https://github.com/docker-mailserver/docker-mailserver/issues
+[gh-issues::dms-fqdn-misconfigured]: https://github.com/docker-mailserver/docker-mailserver/issues/3679#issuecomment-1837609043
 [gh-macos-support]: https://github.com/docker-mailserver/docker-mailserver/issues/3648#issuecomment-1822774080
 [gh-discuss-roundcube-fail2ban]: https://github.com/orgs/docker-mailserver/discussions/3273#discussioncomment-5654603