Values chosen for normalizing to

Some of the changes might seem a little disagreeable to normalize on. I chose to be a bit more verbose (eg the docker-data/dms/ volume prefix), or distinguish "mail server" as "mail-server" as it makes them more easier to grep/search:

• With these changes docker-data/dms/ could be now easily changed to something like ${DMS}//${DATA}//${CONFIG}/ or similar. I don't see harm in keeping the slightly more verbose versions, as it communicates intent and organization clearly, especially for docs with other Docker images and volumes interacting with docker-mailserver.
• Likewise with normalizing mail to mailserver (distinct as the container name/service, not the project/repo/image name or hostname and many other instances of "mail" throughout the docs).

Commit Overview

In addition to the three normalizations below:

• container_name is a minor adjustment in a separate commit.
• drive-by revisions commit contains minor changes I did along the way that aren't tied to the normalization effort, as these have been extracted out into the last commit, they're easily disposable/splittable.
• x2 ssl.md revision focused commits, adjusted config paths for better clarity, and realized the referenced external script is no longer compatible and is further broken by a recent PR merged that changed the internal certs path. Improved cross-documentation with environment.md.

Concerns:

• I normalized hostname: mailserver in the kubernetes page to hostname: mail, there is no domainname:; however I did notice the ENV OVERRIDE_HOSTNAME: mail.example.com setting an FQDN, which I think docker-mailserver startup scripts split to the $HOSTNAME and $DOMAINNAME system ENV vars? (overriding them IIRC)
• kubernetes.md:
  • The config lines apiVersion: extensions/v1beta1, is it still beta status?
  • I tried a quick look at official docs to reference how to configure volumes, but got overwhelmed. I don't know what a PVC is, what is the data name for, is there a host directory to map to? (for normalizing to ./docker-data/dms/)

Observations:

• The normalization PR prior to this one changed example.org in auth-ldap.md to example.com, but AFAIK the rest of the configuration is still for example.org. I've avoided altering LDAP config.
• OVERRIDE_HOSTNAME only exists in docs for environment.md (a definition) and kubernetes.md (a config example).
• $DOMAINNAME and $HOSTNAME system ENV vars should probably be replaced with private/internal vars we manage. These seem historically unreliable/inconsistent to rely on across different container runtimes (even between docker run and docker-compose) and configurations (eg: host network mode). OVERRIDE_HOSTNAME as a workaround with our own internal handling (which is sensitive to base image distro) only further highlights the problem..
• $DOMAINNAME is referenced in the environment.md docs page for SRS, although it seemed to imply it as a ENV docker-mailserver offers and is in control of, I've updated this to clarify it is not. This seems to incorrectly be provided as an ENV via mail_hostname.bats, possibly assumed as valid (ie: no safeguard checks) in some scripts and assigned directly to some files/config or as part of a file path, etc, potentially with different intentions of what this ENV can be, possibly masked by manipulation of the value by scripts. I don't like this, as other software may try to access the dommainname, and this ENV var is not the only source of it, which can cause problems if introducing inconsistent state.. may need to write some test cases for my sanity :)

Normalize mail / mailserver / docker-mailserver where appropriate

Common terms, sometimes interchangeably used or now invalid depending on context: mail, mail container, mail server, mail-server, mailserver,docker-mailserver, Docker Mailserver.

These two regex were used to search docs content (I did not want to risk accidentally missing matches by being too aggressive with broader exclusion sets):

• [^/begGhqs]mail[^s\-=./`AbdEgHMqt]
• [^\-/v]mailserver[^\-/:]

Rough transformations applied to most matches (conditionally, depending on context):

• Docker Mailserver => `docker-mailserver`
• mail container => `docker-mailserver` (optionally retaining ' container')
• mail server => mail-server / `docker-mailserver`
• mail-server => `docker-mailserver`
• mailserver => mail-server / `docker-mailserver`

Additionally I checked docker run (plus exec, logs, etc, sub-commands) and docker-compose commands. Often finding usage of mail instead of the expected mailserver.

Normalize remaining volume paths (especially docker-mailserver volumes mail-*)

• Normalize DMS volume paths to docker-data/dms/mail-{data,state,log}: ./mail, ./mail-state ./data/mail, ./data/state, ./data/logs, ./data/maildata, ./data/mailstate, ./data/maillogs, (dropped/converted data volumes: maildata, mailstate).
• Other docker images also adopt the docker-data/{service name}/ prefix.

Normalize config volume path to docker-data/dms/config/

Normalizing local config path references to ./docker-data/dms/config/: ./config/, config/, `config`, /etc/ (volume mount src path prefix).

Overview:

• full-text-search.md: fts-xapian-plugin.conf, solr-dovecot prefixed with docker-data/dms/config/dovecot/, local file mount /etc/dovecot/conf.d/10-plugin.conf replaced with docker-data/dms/config/dovecot/10-plugin.conf. Might not be appropriate for the solr example, as that is a separate image? (I added it into dms/config/dovecot since it appears Dovecot specific)
• faq.md: cron & cron/sa-learn prefixed with docker-data/dms/ as it looks to be intended as part of the docker-mailserver data, although based on other volume mounts, perhaps it should be docker-data/dms/config/ prefix?. Revised the user-patches FAQ content.
• coding-style.md, setup-stack.sh: config/ in shell notifications/warnings changed to /tmp/docker-mailserver/ which seemed more appropriate.
• user-patches.md: Rephrased some content, retained the config/ mention (that was regarding the repo config/ dir, not the commonly mentioned config volume local directory).
• dkim.md: Split a single-line into multiple & rephrasing it a little while retaining and clarifying the setup.sh default volume mounts local path: ./config/.
• spf.md: Removed /<your docker-mailserver dir>/ to be consistent with the rest of config dir docker-data/dms/config/ usage throughout the docs.
• environment.md: Fixed two docs links were directly referencing the edge version docs, instead of properly linking to docs for that version at the bottom of the page..

Concerns:

• faq.md backup instructions need confirmation that changes are appropriate.
• full-text-search.md shows two examples mounting different local files to the same internal file, and the entire config/ dir volume mount with a file within that dir mounted via a separate volume (as a result of these normalization changes). I am not 100% sure, but I think unlike with data volumes, it can be an issue if volumes have overlapping internal mapped paths (at least when bind mounting a directory). Just mentioning due to potential for volume/config conflicts.
• I need confirmation regarding if docs referencing config/ are equivalent to referencing the internal container path /tmp/docker-mailserver/ (even if that config/ is often referring to the local folder mapping for a volume mount), and never an internal container config/ dir?
• Some of the Dovecot config examples mount files directly to /tmp/docker-mailserver (or mention the hosts local config/ folder), while other examples volume mount files to /etc/dovecot/conf.d. I haven't yet scanned through to ensure this is consistent and correct usage here, but it was something I noticed being a bit inconsistent for Dovecot examples (notably full-text-search.md and imap-folders.md where I deviated a little to normalize to a consistent pattern).
• One issue I have with the current changes proposed is that it's not clear what files can be considered read-only, as I don't think there's a clear separation of what files are intended to be writeable within the config volume mount? This perhaps can be looked into at a later date.

Normalize domains to example.com / not-example.com, and some email accounts to [email protected] / [email protected]

Normalizations:

• Domains normalized to example.com: mywebserver.com, myserver.tld, domain.com, domain.tld, mydomain.net, my-domain.tld, my-domain.com, example.org, whoami.com.
• Alternative domains normalized to not-example.com: otherdomain.com, otherdomain.tld, domain2.tld, mybackupmx.com, whoareyou.org.
• Email addresses normalized to [email protected] (in ssl.md): [email protected], [email protected], [email protected], [email protected].
• Email addresses normalized to [email protected]: [email protected], [email protected], [email protected], [email protected].
• faq.md: A FAQ entry title with sample.domain.com changed to subdomain.example.com.
• mail-fetchmail.md: Config examples with FQDNs for imap/pop3 used example.com domain for a third-party, changed to gmail.com as more familiar third-party/external MTA.

Observations:

• User accounts & aliases noticed in docs (<user>@<domain>): user1, user2, qa, alias1, alias2, user+tag, admin, info, admin.gmail, info.gmail, baduser, address, address+tag, ceo, hr, qa, test.
• Amavis config example escapes @: amavis\@example.com.
• If modifying account names, make sure to check for any related references in the doc page (eg: part of filesystem paths).
• In docs like the FAQ, there is .$mydomain as part of config, this is possibly where some domain name examples derived from.
• coding-style.md: [email protected] changed to [email protected]. Not sure if other is an alias, if it is, should it be changed to alias?

Unaltered (No benefit in changing?):

• ssl.md: example.test.
• faq.md: [email protected].
• relay-hosts.md: domain1.com, domain2.com, domain3.com and relay1.org, relay2.org.
• auth-ldap.md, forward-only-mailserver-with-ldap-authentication.md, environment.md: LDAP specific usage of example.org, mydomain.net seem to be used (note: the TLD is sometimes separate). I'm not familiar with LDAP config to alter this atm.
• understanding-the-ports.md: [email protected], [email protected] (just noting the friend account for example.com).
• introduction.md: smtp.dms.io (FQDN), [email protected], [email protected], [email protected] (similar to [email protected] but intended as separate user).
• setup-stack.sh, check-for-changes.sh: [email protected] (unaltered due to active PRs).

Some occurrences noticed outside of docs (for future reference):

• target/bin/addalias: [email protected], [email protected], [email protected].
• target/bin/delquota: <username@domain>.
• test/config/letsencrypt/{acme.json,acme-changed.json}: [email protected].
• test/config/dovecot-lmtp/conf.d/15-lda.conf: hostname@domain (comment line).
• test/tests.bats: username@fulldomain (docker exec for setquota).

Will review today in the evening (CEST+2).

Documentation preview for this PR is ready! 🎉

Built with commit: 1c3da68

We should from now on keep this level of quality in the docs, especially when reviewing new doc PRs :D

Yeah, while chugging away through this I thought it might be handy to have some common guidelines on jargon, placeholders and such in the contributor docs.

I also thought it might be good to test for URLs to the docs (within the docs) as a lint, that seems to be a recurring mistake that even I've been guilty of sometimes :)

As I didn't get any feedback on raised concerns, I realize the verbose wall of text above might have missed these:

• Kubernetes questions, especially if change to hostname: mail is ok, and if the volume/storage part of configs actually reference local paths. There's also the question about the config referencing some beta extension.
• If you're aware of someone within our community that understands configuring LDAP, please ping them.
• Are the changes to the FAQ on backups ok? @casperklein you're the only other one that has touched these docs since the original author tomav did:
  • Use bind mounts in sample config #2035
  • Backup script improved #1912
• Other concerns have at least been raised here for reference and git blame troubleshooting. Our docs weren't exactly any better in the previous state. If any related issues later surface, the docs can be amended to address those at the time 👍

@georglauterbach and @wernerfred both reviewed and have K8S experience. If one of you could answer those k8s concerns that'd be appreciated 😀

• If you're aware of someone within our community that understands configuring LDAP, please ping them.

@moqmar can you jump in here? Or tag further contributors/users

If one of you could answer those k8s concerns that'd be appreciated 😀

My k8s experience is limited regarding running dms so i would rely on @georglauterbach who actually runs dms in k3s

Kubernetes questions, especially if change to hostname: mail is ok, and if the volume/storage part of configs actually reference local paths. There's also the question about the config referencing some beta extension.

1. The change is okay, because this is a documentation, and you can choose the hostname as you like :) K8s does a bit more magic when it comes to hostnames and routing, but this is fine.
2. When you read beta in K8s, this is mostly because of the way K8s versions its APIs. With our docs, all is well and we needn't worry.

@georglauterbach thanks for that. Does the config examples use any filesystem paths for local persistence? If so I'd like to keep it consistent with docker-data/dms/, provided that's valid in k8s.

@polarathene There is no path in our docs, as volume provisioning is done differently, so no worries.