docs: update docs that cite compose files (#3234)

docs/content/config/advanced/full-text-search.md

@@ -58,13 +58,11 @@ While indexing is memory intensive, you can configure the plugin to limit the am
 2. Update `docker-compose.yml` to load the previously created dovecot plugin config file:
 
     ```yaml
-      version: '3.8'
       services:
         mailserver:
           image: ghcr.io/docker-mailserver/docker-mailserver:latest
           container_name: mailserver
-          hostname: mail
+          hostname: mail.example.com
-          domainname: example.com
           env_file: mailserver.env
           ports:
             - "25:25"    # SMTP  (explicit TLS => STARTTLS)

docs/content/config/advanced/ipv6.md

@@ -12,11 +12,7 @@ This can be solved by supporting IPv6 connections all the way to the `docker-mai
 
 ```diff
 +++ b/serv/docker-compose.yml
-@@ -1,4 +1,4 @@
+@@ ... @@ services:
--version: '2'
-+version: '2.1'
-
-@@ -32,6 +32,16 @@ services:
 
 +  ipv6nat:
 +    image: robbertkl/ipv6nat
@@ -29,7 +25,7 @@ This can be solved by supporting IPv6 connections all the way to the `docker-mai
 +      - /var/run/docker.sock:/var/run/docker.sock:ro
 +      - /lib/modules:/lib/modules:ro
 
-@@ -306,4 +316,13 @@ networks:
+@@ ... @@ networks:
 
 +  default:
 +    driver: bridge

docs/content/config/environment.md

@@ -10,8 +10,10 @@ title: Environment Variables
 
 ##### OVERRIDE_HOSTNAME
 
-- **empty** => uses the `hostname` command to get canonical hostname for `docker-mailserver` to use.
+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 `docker-compose.yml`.
-- => 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 (_eg: you're in a container platform that doesn't let you_) specify it via this environment variable. It will take priority over `docker run` options: `--hostname` and `--domainname`, or `docker-compose.yml` config equivalents: `hostname:` and `domainname:`.
+
+- **empty** => Uses the `hostname -f` command to get canonical hostname for `docker-mailserver` to use.
+- => Specify an FQDN (fully-qualified domain name) to serve mail for. The hostname is required for `docker-mailserver` to function correctly.
 
 ##### LOG_LEVEL
 

docs/content/config/security/ssl.md

@@ -27,43 +27,29 @@ After installation, you can test your setup with:
 
 An [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) (_Fully Qualified Domain Name_) such as `mail.example.com` is required for `docker-mailserver` to function correctly, especially for looking up the correct SSL certificate to use.
 
-Internally, `hostname -f` will be used to retrieve the FQDN as configured in the below examples.
+- `mail.example.com` will still use `user@example.com` as the mail address. You do not need a bare domain for that.
+- We usually discourage assigning a bare domain (_When your DNS MX record does not point to a subdomain_) to represent `docker-mailserver`. However, an FQDN of [just `example.com` is also supported][docs-faq-baredomain].
+- Internally, `hostname -f` will be used to retrieve the FQDN as configured in the below examples.
+- Wildcard certificates (eg: `*.example.com`) are supported for `SSL_TYPE=letsencrypt`. Your configured FQDN below may be `mail.example.com`, and your wildcard certificate provisioned to `/etc/letsencrypt/live/example.com` which will be checked as a fallback FQDN by `docker-mailserver`.
 
-Wildcard certificates (eg: `*.example.com`) are supported for `SSL_TYPE=letsencrypt`. Your configured FQDN below may be `mail.example.com`, and your wildcard certificate provisioned to `/etc/letsencrypt/live/example.com` which will be checked as a fallback FQDN by `docker-mailserver`.
+!!! example "Setting the hostname correctly"
 
-!!! example "Docker CLI options `--hostname` and optionally `--domainname`"
+    Change `mail.example.com` below to your own FQDN.
 
     ```sh
-    docker run --hostname mail --domainname example.com
+    # CLI:
-    # `--domainname` is not required:
     docker run --hostname mail.example.com
     ```
     
-!!! example "`docker-compose.yml` config"
+    or
     
     ```yml
-    services:
+    # docker-compose.yml
-      mailserver:
-        hostname: mail
-        domainname: example.com
-    # `domainname` is not required:
     services:
       mailserver:
         hostname: mail.example.com
     ```
 
-!!! example "_Bare domains_ (eg: `example.com`) should only use the hostname option"
-
-    ```sh
-    docker run --hostname example.com
-    ```
-
-    ```yml
-    services:
-      mailserver:
-        hostname: example.com
-    ```
-
 ## Provisioning methods
 
 ### Let's Encrypt (Recommended)
@@ -91,9 +77,7 @@ You don't have to do anything else. Enjoy!
     ```yaml
     services:
       mailserver:
-        # For the FQDN 'mail.example.com':
+        hostname: mail.example.com
-        hostname: mail
-        domainname: example.com
         environment:
           - SSL_TYPE=letsencrypt
         volumes:
@@ -107,7 +91,6 @@ Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store the
 1. Getting a certificate is this simple! (_Referencing: [Certbot docker instructions][certbot::docker] and [`certonly --standalone` mode][certbot::standalone]_):
 
     ```sh
-    # Change `mail.example.com` below to your own FQDN.
     # Requires access to port 80 from the internet, adjust your firewall if needed.
     docker run --rm -it \
       -v "${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/" \
@@ -125,9 +108,7 @@ Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store the
         ```yaml
         services:
           mailserver:
-            # For the FQDN 'mail.example.com':
+            hostname: mail.example.com
-            hostname: mail
-            domainname: example.com
             environment:
               - SSL_TYPE=letsencrypt
             volumes:
@@ -367,7 +348,6 @@ The following example is the [basic setup][acme-companion::basic-setup] you need
     You should have an existing `docker-compose.yml` with a `mailserver` service. Below are the modifications to add for integrating with `nginx-proxy` and `acme-companion` services:
 
     ```yaml
-    version: '3.8'
     services:
       # Add the following `environment` and `volumes` to your existing `mailserver` service:
       mailserver:
@@ -395,12 +375,10 @@ The following example is the [basic setup][acme-companion::basic-setup] you need
         volumes:
           # `certs/`:      Managed by the `acme-companion` container (_read-only_).
           # `docker.sock`: Required to interact with containers via the Docker API.
-          # `dhparam`:     A named data volume to prevent `nginx-proxy` creating an anonymous volume each time.
           - ./docker-data/nginx-proxy/html/:/usr/share/nginx/html/
           - ./docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/
           - ./docker-data/acme-companion/certs/:/etc/nginx/certs/:ro
           - /var/run/docker.sock:/tmp/docker.sock:ro
-          - dhparam:/etc/nginx/dhparam
 
       acme-companion:
         image: nginxproxy/acme-companion
@@ -421,12 +399,6 @@ The following example is the [basic setup][acme-companion::basic-setup] you need
           - ./docker-data/acme-companion/certs/:/etc/nginx/certs/:rw
           - ./docker-data/acme-companion/acme-state/:/etc/acme.sh/
           - /var/run/docker.sock:/var/run/docker.sock:ro
-
-    # Once `nginx-proxy` fixes their Dockerfile, this named data volume can be removed from docs.
-    # Users can opt for a local bind mount volume like all others if they prefer, but this volume
-    # is only intended to be temporary.
-    volumes:
-      dhparam:
     ```
 
 !!! tip "Optional ENV vars worth knowing about"
@@ -494,8 +466,6 @@ Amongst other things, you can use these to secure your mail-server. DSM locates
 Navigate to that folder and note the 6 character random folder name of the certificate you'd like to use. Then, add the following to your `docker-compose.yml` declaration file:
 
 ```yaml
-# Note: If you have an existing setup that was working pre docker-mailserver v10.2,
-# '/tmp/dms/custom-certs' below has replaced the previous '/tmp/ssl' container path.
 volumes:
   - /usr/syno/etc/certificate/_archive/<your-folder>/:/tmp/dms/custom-certs/
 environment:
@@ -508,16 +478,6 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
 
 ### Caddy
 
-If you are using Caddy to renew your certificates, please note that only RSA certificates work. Read [#1440][github-issue-1440] for details. In short for Caddy v1 the `Caddyfile` should look something like:
-
-```caddyfile
-https://mail.example.com {
-  tls admin@example.com {
-    key_type rsa2048
-  }
-}
-```
-
 For Caddy v2 you can specify the `key_type` in your server's global settings, which would end up looking something like this if you're using a `Caddyfile`:
 
 ```caddyfile
@@ -533,7 +493,7 @@ For Caddy v2 you can specify the `key_type` in your server's global settings, wh
 
 If you are instead using a json config for Caddy v2, you can set it in your site's TLS automation policies:
 
-???+ example "Example Code"
+??? example "Caddy v2 JSON example snippet"
 
     ```json
     {
@@ -600,7 +560,7 @@ If you are instead using a json config for Caddy v2, you can set it in your site
     }
     ```
 
-The generated certificates can be mounted:
+The generated certificates can then be mounted:
 
 ```yaml
 volumes:
@@ -608,15 +568,6 @@ volumes:
   - ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.key:/etc/letsencrypt/live/mail.example.com/privkey.pem
 ```
 
-EC certificates fail in the TLS handshake:
-
-```log
-CONNECTED(00000003)
-140342221178112:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure:ssl/record/rec_layer_s3.c:1543:SSL alert number 40
-no peer certificate available
-No client certificate CA names sent
-```
-
 ### Traefik v2
 
 [Traefik][traefik::github] is an open-source application proxy using the [ACME protocol][ietf::rfc::acme]. [Traefik][traefik::github] can request certificates for domains and subdomains, and it will take care of renewals, challenge negotiations, etc. We strongly recommend to use [Traefik][traefik::github]'s major version 2.
@@ -637,13 +588,11 @@ This setup only comes with one caveat: The domain has to be configured on anothe
     Here is an example setup for [`docker-compose`](https://docs.docker.com/compose/):
 
     ```yaml
-    version: '3.8'
     services:
       mailserver:
         image: ghcr.io/docker-mailserver/docker-mailserver:latest
         container_name: mailserver
-        hostname: mail
+        hostname: mail.example.com
-        domainname: example.com
         volumes:
            - ./docker-data/traefik/acme.json:/etc/letsencrypt/acme.json:ro
         environment:
@@ -927,10 +876,10 @@ Despite this, if you must use non-standard DH parameters or you would like to sw
 
 [docs-env::ssl-type]: ../environment.md#ssl_type
 [docs-optional-config]: ../advanced/optional-config.md
+[docs-faq-baredomain]: ../../faq.md#can-i-use-a-nakedbare-domain-ie-no-hostname
 
 [github-file-compose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/docker-compose.yml
 [github-file::tls-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/3b8059f2daca80d967635e04d8d81e9abb755a4d/test/test-files/ssl/example.test/README.md
-[github-issue-1440]: https://github.com/docker-mailserver/docker-mailserver/issues/1440
 [hanscees-renewcerts]: https://github.com/hanscees/dockerscripts/blob/master/scripts/tomav-renew-certs
 
 [traefik::github]: https://github.com/containous/traefik

docs/content/examples/tutorials/mailserver-behind-proxy.md

@@ -30,7 +30,6 @@ Feel free to add your configuration if you achieved the same goal using differen
     Truncated configuration of traefik itself:
 
     ```yaml
-    version: '3.8'
     services:
       reverse-proxy:
         image: docker.io/traefik:latest # v2.5
@@ -57,13 +56,11 @@ Feel free to add your configuration if you achieved the same goal using differen
     Truncated list of necessary labels on the `docker-mailserver` container:
 
     ```yaml
-    version: '3.8'
     services:
       mailserver:
         image: ghcr.io/docker-mailserver/docker-mailserver:latest
         container_name: mailserver
-        hostname: mail
+        hostname: mail.example.com
-        domainname: example.com
         restart: always
         networks:
           - proxy

docs/content/faq.md

@@ -168,7 +168,7 @@ To use a bare domain (_where the host name is `example.com` and the domain is al
 - From: `mydestination = $myhostname, localhost.$mydomain, localhost`
 - To: `mydestination = localhost.$mydomain, localhost`
 
-Add the latter line to `docker-data/dms/config/postfix-main.cf`. If that doesn't work, make sure that `OVERRIDE_HOSTNAME` is blank in your `mailserver.env` file (see [#1731](https://github.com/docker-mailserver/docker-mailserver/issues/1731#issuecomment-753968425)). Without these changes there will be warnings in the logs like:
+Add the latter line to `docker-data/dms/config/postfix-main.cf`. If that doesn't work, make sure that [`OVERRIDE_HOSTNAME` is blank in your `mailserver.env` file][github-comment-override-hostname]. Without these changes there will be warnings in the logs like:
 
 ```log
 warning: do not list domain example.com in BOTH mydestination and virtual_mailbox_domains
@@ -176,7 +176,15 @@ warning: do not list domain example.com in BOTH mydestination and virtual_mailbo
 
 Plus of course mail delivery fails.
 
-Also you need to define `hostname: example.com` in your docker-compose.yml and don't sepecify the `domainname:` at all.
+Also you need to define `hostname: example.com` in your `docker-compose.yml`.
+
+!!! tip "You might not want a bare domain"
+
+    We encourage you to consider using a subdomain where possible.
+    
+    - There are [benefits][github-comment-baredomain] to preferring a subdomain.
+    - A bare domain is not required to have `user@example.com`, that is distinct from your hostname which is identified by a DNS MX record.
+
 
 ### How can I configure a catch-all?
 
@@ -453,8 +461,6 @@ The following configuration works nicely:
     Or with [Docker Swarm](https://docs.docker.com/engine/swarm/configs/):
 
     ```yaml
-    version: '3.8'
-
     services:
       mailserver:
         image: ghcr.io/docker-mailserver/docker-mailserver:latest
@@ -519,6 +525,8 @@ $spam_quarantine_to       = "amavis\@example.com";
 [fail2ban-customize]: ./config/security/fail2ban.md
 [docs-maintenance]: ./config/advanced/maintenance/update-and-cleanup.md
 [docs-userpatches]: ./config/advanced/override-defaults/user-patches.md
+[github-comment-baredomain]: https://github.com/docker-mailserver/docker-mailserver/issues/3048#issuecomment-1432358353
+[github-comment-override-hostname]: https://github.com/docker-mailserver/docker-mailserver/issues/1731#issuecomment-753968425
 [github-issue-95]: https://github.com/docker-mailserver/docker-mailserver/issues/95
 [github-issue-97]: https://github.com/docker-mailserver/docker-mailserver/issues/97
 [github-issue-1247]: https://github.com/docker-mailserver/docker-mailserver/issues/1247