docs(chore): Normalize for consistency (#2206)

"Brief" summary/overview of changes. See the PR discussion or individual commits from the PR for more details.

---

Only applies to the `docs/content/**` content (_and `setup` command_). `target/` and `test/` can be normalized at a later date.

* Normalize to `example.com`

- 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 `admin@example.com` (in `ssl.md`): `foo@bar.com`, `yourcurrentemail@gmail.com`, `email@email.com`, `admin@domain.tld`.
- Email addresses normalized to `external-account@gmail.com`: `bill@gates321boom.com`, `external@gmail.com`, `myemail@gmail.com`, `real-email-address@external-domain.com`.
- **`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.

* Normalize config volume path

- Normalizing local config path references to `./docker-data/dms/config/`: `./config/`, `config/`, \``config`\`, `/etc/` (_volume mount src path prefix_).
- 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.

* `ssl.md` - Use `dms/custom-certs` where appropriate.

* Apply normalizations to README and example `docker-compose.yml`

---

Common terms, sometimes interchangeably used or now invalid depending on context: `mail`, `mail container`, `mail server`, `mail-server`, `mailserver`,`docker-mailserver`, `Docker 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`

Additionally changes `mailserver` hostname in k8s to `mail` to align with other non-k8s examples.

---

* drive-by revisions

Mostly minor revisions or improvements to docs that aren't related to normalization effort.
This commit is contained in:
Brennan Kinney 2021-09-23 11:29:37 +12:00 committed by GitHub
parent 5b9d1f9120
commit a0ee472501
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
40 changed files with 544 additions and 503 deletions

View file

@ -4,7 +4,7 @@ hide:
- toc
---
[`setup.sh`][github-file-setupsh] is an administration script that helps with the most common tasks, including initial configuration. It is intended to be used from the host machine, _not_ from within your running container.
[`setup.sh`][github-file-setupsh] is an administration script that helps with the most common tasks, including initial configuration. It is intended to be run from the host machine, _not_ from inside your running container.
The latest version of the script is included in the `docker-mailserver` repository. You may retrieve it at any time by running this command in your console:
@ -13,9 +13,9 @@ wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/maste
chmod a+x ./setup.sh
```
!!! warning "`setup.sh` for Docker Mailserver version `v10.1.x` and below"
!!! warning "`setup.sh` for `docker-mailserver` version `v10.1.x` and below"
If you're using Docker Mailserver version `v10.1.x` or below, you will need to get `setup.sh` with a specific version. Substitute `<VERSION>` with the [tagged release version](https://github.com/docker-mailserver/docker-mailserver/tags) that you're using:
If you're using `docker-mailserver` version `v10.1.x` or below, you will need to get `setup.sh` with a specific version. Substitute `<VERSION>` with the [tagged release version](https://github.com/docker-mailserver/docker-mailserver/tags) that you're using:
`wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/<VERSION>/setup.sh`.
@ -35,12 +35,12 @@ SYNOPSIS
COMMAND := { email | alias | quota | config | relay | debug } SUBCOMMAND
DESCRIPTION
This is the main administration script that you use for all interactions with your
mail server. Setup, configuration and much more is done with this script.
This is the main administration script that you use for all your interactions with
'docker-mailserver'. Setup, configuration and much more is done with this script.
Please note that the script executes most of the commands inside the container itself.
If the image was not found, this script will pull the :latest tag of
mailserver/docker-mailserver. This tag refers to the latest release,
If the image was not found, this script will pull the ':latest' tag of
'mailserver/docker-mailserver'. This tag refers to the latest release,
see the tagging convention in the README under
https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md
@ -81,30 +81,30 @@ DESCRIPTION
./setup.sh debug login <COMMANDS>
EXAMPLES
./setup.sh email add test@domain.tld
Add the email account test@domain.tld. You will be prompted
./setup.sh email add test@example.com
Add the email account test@example.com. You will be prompted
to input a password afterwards since no password was supplied.
./setup.sh config dkim keysize 2048 domain 'whoami.com,whoareyou.org'
./setup.sh config dkim keysize 2048 domain 'example.com,not-example.com'
Creates keys of length 2048 but in an LDAP setup where domains are not known to
Postfix by default, so you need to provide them yourself in a comma-separated list.
./setup.sh config dkim help
This will provide you with a detailed explanation on how to use the
This will provide you with a detailed explanation on how to use the
config dkim command, showing what arguments can be passed and what they do.
OPTIONS
Config path, container or image adjustments
-i IMAGE_NAME
Provides the name of the docker-mailserver image. The default value is
docker.io/mailserver/docker-mailserver:latest
Provides the name of the 'docker-mailserver' image. The default value is
'docker.io/mailserver/docker-mailserver:latest'
-c CONTAINER_NAME
Provides the name of the running container.
-p PATH
Provides the config folder path to the temporary container
(does not work if docker-mailserver container already exists).
Provides the config folder path to the temporary container
(does not work if a 'docker-mailserver' container already exists).
SELinux
-z