mir/docker-mailserver
2
0
Fork 0
mirror of https://github.com/tomav/docker-mailserver synced 2025-08-31 06:15:28 +00:00
Code Issues Releases Wiki Activity

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

Browse Source 
"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
40 changed files with 544 additions and 503 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/content/examples/tutorials/basic-installation.md
View File

@@ -2,18 +2,18 @@
title: 'Tutorials | Basic Installation'
---
## Building a Simple Mailserver
## Building a Simple Mail-Server
!!! warning
Adding the docker network's gateway to the list of trusted hosts, e.g. using the `network` or `connected-networks` option, can create an [**open relay**](https://en.wikipedia.org/wiki/Open_mail_relay), for instance [if IPv6 is enabled on the host machine but not in Docker][github-issue-1405-comment].
We are going to use this docker based mailserver:
- First create a directory for the mailserver and get the setup script:
- First create a directory for `docker-mailserver` to store data in, and get the `setup.sh` script:
```sh
mkdir -p /var/ds/mail.example.org
cd /var/ds/mail.example.org/
mkdir -p /var/ds/mail.example.com
cd /var/ds/mail.example.com/
curl -o setup.sh \
https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/setup.sh
@@ -30,19 +30,19 @@ We are going to use this docker based mailserver:
services:
mailserver:
image: docker.io/mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail
domainname: example.com
container_name: mailserver
ports:
- "25:25"
- "587:587"
- "465:465"
volumes:
- ./data/maildata:/var/mail
- ./data/mailstate:/var/mail-state
- ./data/maillogs:/var/log/mail
- ./docker-data/dms/mail-data/:/var/mail/
- ./docker-data/dms/mail-state/:/var/mail-state/
- ./docker-data/dms/mail-logs/:/var/log/mail/
- ./docker-data/dms/config/:/tmp/docker-mailserver/
- /etc/localtime:/etc/localtime:ro
- ./config/:/tmp/docker-mailserver/
- /var/ds/wsproxy/letsencrypt/:/etc/letsencrypt/
environment:
- PERMIT_DOCKER=network
@@ -65,7 +65,7 @@ We are going to use this docker based mailserver:
- [Environment Variables][docs-environment]
- [`mailserver.env` file][github-file-dotenv]
Make sure to set the proper `domainname` that you will use for the emails. We forward only SMTP ports (not POP3 and IMAP) because we are not interested in accessing the mailserver directly (from a client). We also use these settings:
Make sure to set the proper `domainname` that you will use for the emails. We forward only SMTP ports (not POP3 and IMAP) because we are not interested in accessing the mail-server directly (from a client). We also use these settings:
- `PERMIT_DOCKER=network` because we want to send emails from other docker containers.
- `SSL_TYPE=letsencrypt` because we will manage SSL certificates with letsencrypt.
@@ -82,12 +82,12 @@ We are going to use this docker based mailserver:
- Pull the docker image: `docker pull mailserver/docker-mailserver:latest`
- Now generate the DKIM keys with `./setup.sh config dkim` and copy the content of the file `config/opendkim/keys/domain.tld/mail.txt` on the domain zone configuration at the DNS server. I use [bind9](https://github.com/docker-scripts/bind9) for managing my domains, so I just paste it on `example.org.db`:
- Now generate the DKIM keys with `./setup.sh config dkim` and copy the content of the file `docker-data/dms/config/opendkim/keys/example.com/mail.txt` on the domain zone configuration at the DNS server. I use [bind9](https://github.com/docker-scripts/bind9) for managing my domains, so I just paste it on `example.com.db`:
```txt
mail._domainkey IN TXT ( "v=DKIM1; h=sha256; k=rsa; "
"p=MIIBIjANBgkqhkiG9w0BAQEFACAQ8AMIIBCgKCAQEAaH5KuPYPSF3Ppkt466BDMAFGOA4mgqn4oPjZ5BbFlYA9l5jU3bgzRj3l6/Q1n5a9lQs5fNZ7A/HtY0aMvs3nGE4oi+LTejt1jblMhV/OfJyRCunQBIGp0s8G9kIUBzyKJpDayk2+KJSJt/lxL9Iiy0DE5hIv62ZPP6AaTdHBAsJosLFeAzuLFHQ6USyQRojefqFQtgYqWQ2JiZQ3"
"iqq3bD/BVlwKRp5gH6TEYEmx8EBJUuDxrJhkWRUk2VDl1fqhVBy8A9O7Ah+85nMrlOHIFsTaYo9o6+cDJ6t1i6G1gu+bZD0d3/3bqGLPBQV9LyEL1Rona5V7TJBGg099NQkTz1IwIDAQAB" ) ; ----- DKIM key mail for example.org
"iqq3bD/BVlwKRp5gH6TEYEmx8EBJUuDxrJhkWRUk2VDl1fqhVBy8A9O7Ah+85nMrlOHIFsTaYo9o6+cDJ6t1i6G1gu+bZD0d3/3bqGLPBQV9LyEL1Rona5V7TJBGg099NQkTz1IwIDAQAB" ) ; ----- DKIM key mail for example.com
```
- Add these configurations as well on the same file on the DNS server:
@@ -95,8 +95,8 @@ We are going to use this docker based mailserver:
```txt
mail IN A 10.11.12.13
; mailservers for example.org
3600 IN MX 1 mail.example.org.
; mail-server for example.com
3600 IN MX 1 mail.example.com.
; Add SPF record
IN TXT "v=spf1 mx ~all"
@@ -108,55 +108,55 @@ We are going to use this docker based mailserver:
```sh
cd /var/ds/wsproxy
ds domains-add mail mail.example.org
ds get-ssl-cert myemail@gmail.com mail.example.org --test
ds get-ssl-cert myemail@gmail.com mail.example.org
ds domains-add mail mail.example.com
ds get-ssl-cert external-account@gmail.com mail.example.com --test
ds get-ssl-cert external-account@gmail.com mail.example.com
```
Now the certificates will be available on `/var/ds/wsproxy/letsencrypt/live/mail.example.org`.
Now the certificates will be available on `/var/ds/wsproxy/letsencrypt/live/mail.example.com`.
- Start the mailserver and check for any errors:
- Start `docker-mailserver` and check for any errors:
```sh
apt install docker-compose
docker-compose up mail
docker-compose up mailserver
```
- Create email accounts and aliases with `SPOOF_PROTECTION=0`:
```sh
./setup.sh email add admin@example.org passwd123
./setup.sh email add info@example.org passwd123
./setup.sh alias add admin@example.org myemail@gmail.com
./setup.sh alias add info@example.org myemail@gmail.com
./setup.sh email add admin@example.com passwd123
./setup.sh email add info@example.com passwd123
./setup.sh alias add admin@example.com external-account@gmail.com
./setup.sh alias add info@example.com external-account@gmail.com
./setup.sh email list
./setup.sh alias list
```
Aliases make sure that any email that comes to these accounts is forwarded to my real email address, so that I don't need to use POP3/IMAP in order to get these messages. Also no anti-spam and anti-virus software is needed, making the mailserver lighter.
Aliases make sure that any email that comes to these accounts is forwarded to my real email address, so that I don't need to use POP3/IMAP in order to get these messages. Also no anti-spam and anti-virus software is needed, making the mail-server lighter.
- Or create email accounts and aliases with `SPOOF_PROTECTION=1`:
```sh
./setup.sh email add admin.gmail@example.org passwd123
./setup.sh email add info.gmail@example.org passwd123
./setup.sh alias add admin@example.org admin.gmail@example.org
./setup.sh alias add info@example.org info.gmail@example.org
./setup.sh alias add admin.gmail@example.org myemail@gmail.com
./setup.sh alias add info.gmail@example.org myemail@gmail.com
./setup.sh email add admin.gmail@example.com passwd123
./setup.sh email add info.gmail@example.com passwd123
./setup.sh alias add admin@example.com admin.gmail@example.com
./setup.sh alias add info@example.com info.gmail@example.com
./setup.sh alias add admin.gmail@example.com external-account@gmail.com
./setup.sh alias add info.gmail@example.com external-account@gmail.com
./setup.sh email list
./setup.sh alias list
```
This extra step is required to avoid the `553 5.7.1 Sender address rejected: not owned by user` error (the account used for setting up Gmail is `admin.gmail@example.org` and `info.gmail@example.org` )
This extra step is required to avoid the `553 5.7.1 Sender address rejected: not owned by user` error (the account used for setting up Gmail is `admin.gmail@example.com` and `info.gmail@example.com` )
- Send some test emails to these addresses and make other tests. Then stop the container with `ctrl+c` and start it again as a daemon: `docker-compose up -d mail`.
- Send some test emails to these addresses and make other tests. Then stop the container with `ctrl+c` and start it again as a daemon: `docker-compose up -d mailserver`.
- Now save on Moodle configuration the SMTP settings and test by trying to send some messages to other users:
- **SMTP hosts**: `mail.example.org:465`
- **SMTP hosts**: `mail.example.com:465`
- **SMTP security**: `SSL`
- **SMTP username**: `info@example.org`
- **SMTP username**: `info@example.com`
- **SMTP password**: `passwd123`
[docs-environment]: ../../config/environment.md

8
docs/content/examples/tutorials/blog-posts.md
View File

@@ -2,8 +2,8 @@
title: 'Tutorials | Blog Posts'
---
This site lists blog entries that write about the project. If you blogged about `docker-mailserver` as well feel free to add your site!
This site lists blog entries that write about the project. If you blogged about `docker-mailserver` let us know so we can add it here!
- [Installing docker-mailserver](https://lowtek.ca/roo/2021/installing-docker-mailserver/) by [@andrewlow](https://github.com/andrewlow)
- [Simple Mailserver with docker](https://tvi.al/simple-mail-server-with-docker/) by [@tomav](https://github.com/tomav)
- [Self hosted mail server](https://www.ifthenel.se/self-hosted-mail-server/) by [@matrixes](https://github.com/matrixes)
- [Installing docker-mailserver](https://lowtek.ca/roo/2021/installing-docker-mailserver/) by [@andrewlow](https://github.com/andrewlow)
- [Simple mail-server with docker](https://tvi.al/simple-mail-server-with-docker/) by [@tomav](https://github.com/tomav)
- [Self hosted mail-server](https://www.ifthenel.se/self-hosted-mail-server/) by [@matrixes](https://github.com/matrixes)

18
docs/content/examples/tutorials/mailserver-behind-proxy.md
View File

@@ -1,5 +1,5 @@
---
title: 'Tutorials | Mailserver behind Proxy'
title: 'Tutorials | Mail-Server behind a Proxy'
---
## Using `docker-mailserver` behind a Proxy
@@ -23,17 +23,17 @@ Luckily `dovecot` and `postfix` are both Proxy-Protocol ready softwares so it de
The configuration depends on the used proxy system. I will provide the configuration examples of [traefik v2](https://traefik.io/) using IMAP and SMTP with implicit TLS.
Feel free to add your configuration if you archived the same goal using different proxy software below:
Feel free to add your configuration if you achieved the same goal using different proxy software below:
??? "Traefik v2"
Truncated configuration of traefik itself:
```yaml
version: '3.7'
version: '3.8'
services:
reverse-proxy:
image: traefik:latest
image: docker.io/traefik:latest # v2.5
container_name: docker-traefik
restart: always
command:
@@ -54,16 +54,16 @@ Feel free to add your configuration if you archived the same goal using differen
[...]
```
Truncated list of necessary labels on the mailserver container:
Truncated list of necessary labels on the `docker-mailserver` container:
```yaml
version: '3.8'
services:
mailserver:
image: docker.io/mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail
domainname: example.com
container_name: mailserver
restart: always
networks:
- proxy
@@ -98,20 +98,20 @@ Feel free to add your configuration if you archived the same goal using differen
The following changes can be achieved completely by adding the content to the appropriate files by using the projects [function to overwrite config files][docs-optionalconfig].
Changes for `postfix` can be applied by adding the following content to `config/postfix-main.cf`:
Changes for `postfix` can be applied by adding the following content to `docker-data/dms/config/postfix-main.cf`:
```cf
postscreen_upstream_proxy_protocol = haproxy
```
and to `config/postfix-master.cf`:
and to `docker-data/dms/config/postfix-master.cf`:
```cf
submission/inet/smtpd_upstream_proxy_protocol=haproxy
smtps/inet/smtpd_upstream_proxy_protocol=haproxy
```
Changes for `dovecot` can be applied by adding the following content to `config/dovecot.cf`:
Changes for `dovecot` can be applied by adding the following content to `docker-data/dms/config/dovecot.cf`:
```cf
haproxy_trusted_networks = <your-proxy-ip>, <optional-cidr-notation>

22
docs/content/examples/uses-cases/forward-only-mailserver-with-ldap-authentication.md
View File

@@ -1,10 +1,10 @@
---
title: 'Use Cases | Forward-Only Mailserver with LDAP'
title: 'Use Cases | Forward-Only Mail-Server with LDAP'
---
## Building a Forward-Only Mailserver
## Building a Forward-Only Mail-Server
A **forward-only** mailserver does not have any local mailboxes. Instead, it has only aliases that forward emails to external email accounts (for example to a Gmail account). You can also send email from the localhost (the computer where the mailserver is installed), using as sender any of the alias addresses.
A **forward-only** mail-server does not have any local mailboxes. Instead, it has only aliases that forward emails to external email accounts (for example to a Gmail account). You can also send email from the localhost (the computer where `docker-mailserver` is installed), using as sender any of the alias addresses.
The important settings for this setup (on `mailserver.env`) are these:
@@ -27,7 +27,7 @@ We can create aliases with `./setup.sh`, like this:
## Authenticating with LDAP
If you want to send emails from outside the mailserver you have to authenticate somehow (with a username and password). One way of doing it is described in [this discussion][github-issue-1247]. However if there are many user accounts, it is better to use authentication with LDAP. The settings for this on `mailserver.env` are:
If you want to send emails from outside the mail-server you have to authenticate somehow (with a username and password). One way of doing it is described in [this discussion][github-issue-1247]. However if there are many user accounts, it is better to use authentication with LDAP. The settings for this on `mailserver.env` are:
```env
ENABLE_LDAP=1
@@ -47,7 +47,7 @@ SASLAUTHD_LDAP_SEARCH_BASE=ou=users,dc=example,dc=org
SASLAUTHD_LDAP_FILTER=(&(uid=%U)(objectClass=inetOrgPerson))
```
My LDAP data structure is very basic, containing only the username, password, and the external email address where to forward emails for this user. An entry looks like this
My LDAP data structure is very basic, containing only the username, password, and the external email address where to forward emails for this user. An entry looks like this:
```properties
add uid=username,ou=users,dc=example,dc=org
@@ -56,10 +56,10 @@ objectClass: inetOrgPerson
sn: username
cn: username
userPassword: {SSHA}abcdefghi123456789
email: real-email-address@external-domain.com
email: external-account@gmail.com
```
This structure is different from what is expected/assumed from the configuration scripts of the mailserver, so it doesn't work just by using the `LDAP_QUERY_FILTER_...` settings. Instead, I had to do [custom configuration][github-file-readme-patches]. I created the script `config/user-patches.sh`, with a content like this:
This structure is different from what is expected/assumed from the configuration scripts of `docker-mailserver`, so it doesn't work just by using the `LDAP_QUERY_FILTER_...` settings. Instead, I had to use a custom configuration ([via `user-patches.sh`][docs-userpatches]). I created the script `docker-data/dms/config/user-patches.sh`, with content like this:
```bash
#!/bin/bash
@@ -96,17 +96,17 @@ postfix reload
You see that besides `query_filter`, I had to customize as well `result_attribute` and `result_format`.
!!! seealso "See also"
!!! note "See also"
For more details about using LDAP see: [LDAP managed mail server with Postfix and Dovecot for multiple domains](https://www.vennedey.net/resources/2-LDAP-managed-mail-server-with-Postfix-and-Dovecot-for-multiple-domains)
For more details about using LDAP see: [LDAP managed mail-server with Postfix and Dovecot for multiple domains](https://www.vennedey.net/resources/2-LDAP-managed-mail-server-with-Postfix-and-Dovecot-for-multiple-domains)
!!! note
Another solution that serves as a forward-only mailserver is this: https://gitlab.com/docker-scripts/postfix
Another solution that serves as a forward-only mail-server is [this](https://gitlab.com/docker-scripts/postfix).
!!! tip
One user reports only having success if `ENABLE_LDAP=0` was set.
[github-file-readme-patches]: https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md#custom-user-changes--patches
[docs-userpatches]: ./config/advanced/override-defaults/user-patches.md
[github-issue-1247]: https://github.com/docker-mailserver/docker-mailserver/issues/1247

7
docs/content/examples/uses-cases/imap-folders.md
View File

@@ -16,12 +16,11 @@ See [`target/dovecot/15-mailboxes.conf`][gh-config-dovecot-mailboxes] for existi
The `Archive` special IMAP folder may be useful to enable. To do so, make a copy of [`target/dovecot/15-mailboxes.conf`][gh-config-dovecot-mailboxes] and uncomment the `Archive` mailbox definition. Mail clients should understand that this folder is intended for archiving mail due to the [`\Archive` _"SPECIAL-USE"_ attribute][rfc-6154].
With the provided [docker-compose.yml][gh-config-dockercompose] example, a volume bind mounts the host directory `config` to the container location `/tmp/docker-mailserver`. Config file overrides should instead be mounted to a different location as described in [Overriding Configuration for Dovecot][docs-config-overrides-dovecot]:
With the provided [docker-compose.yml][gh-config-dockercompose] example, a volume bind mounts the host directory `docker-data/dms/config/` to the container location `/tmp/docker-mailserver/`. Config file overrides should instead be mounted to a different location as described in [Overriding Configuration for Dovecot][docs-config-overrides-dovecot]:
```YAML
```yaml
volumes:
...
- ./config/dovecot/15-mailboxes.conf:/etc/dovecot/conf.d/15-mailboxes.conf:ro
- ./docker-data/dms/config/dovecot/15-mailboxes.conf:/etc/dovecot/conf.d/15-mailboxes.conf:ro
```
## Caution