mirror/docker-mailserver.docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2025-06-28 03:30:24 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

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
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
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>