github-com-docker-mailserver/docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2024-01-19 02:48:50 +00:00
Code Issues Projects Releases Wiki Activity

Better incorporate the new, great documentation (#1878)

Browse source
This commit is contained in:
Georg Lauterbach 2021-04-01 22:44:31 +02:00 committed by GitHub
parent f3652e52c8
commit 65622c56e9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 67 additions and 65 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

83
README.md
View file

@ -1,15 +1,17 @@
# Docker Mailserver # Docker Mailserver
[![ci::status]][ci::github] [![docker::pulls]][docker::hub] [![ci::status]][ci::github] [![docker::pulls]][docker::hub] [![documentation::badge]][documentation::web]
[ci::status]: https://img.shields.io/github/workflow/status/docker-mailserver/docker-mailserver/Build%2C%20Test%20%26%20Deploy?color=blue&label=CI&logo=github&logoColor=white&style=for-the-badge [ci::status]: https://img.shields.io/github/workflow/status/docker-mailserver/docker-mailserver/Build%2C%20Test%20%26%20Deploy?color=blue&label=CI&logo=github&logoColor=white&style=for-the-badge
[ci::github]: https://github.com/docker-mailserver/docker-mailserver/actions [ci::github]: https://github.com/docker-mailserver/docker-mailserver/actions
[docker::pulls]: https://img.shields.io/docker/pulls/mailserver/docker-mailserver.svg?style=for-the-badge&logo=docker&logoColor=white [docker::pulls]: https://img.shields.io/docker/pulls/mailserver/docker-mailserver.svg?style=for-the-badge&logo=docker&logoColor=white
[docker::hub]: https://hub.docker.com/r/mailserver/docker-mailserver/ [docker::hub]: https://hub.docker.com/r/mailserver/docker-mailserver/
[documentation::badge]: https://img.shields.io/badge/DOCUMENTATION-GH%20PAGES-0078D4?style=for-the-badge&logo=git&logoColor=white
[documentation::web]: https://docker-mailserver.github.io/docker-mailserver/edge/
A fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.). Only configuration files, no SQL database. Keep it simple and versioned. Easy to deploy and upgrade. A fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.). Only configuration files, no SQL database. Keep it simple and versioned. Easy to deploy and upgrade. [Documentation][documentation::web] via MkDocs. [Why this image was created.](https://tvi.al/simple-mail-server-with-docker/).
[Why this image was created.](http://tvi.al/simple-mail-server-with-docker/) If you have issues, read the full `README` **and** the [documentation][documentation::web] **for your version** (default is `edge`) first **before opening an issue**. The issue tracker is for issues, not for personal support.
1. [Included Services](#included-services) 1. [Included Services](#included-services)
2. [Issues and Contributing](./CONTRIBUTING.md) 2. [Issues and Contributing](./CONTRIBUTING.md)
@ -17,7 +19,8 @@ A fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.)
4. [Usage](#usage) 4. [Usage](#usage)
5. [Examples](#examples) 5. [Examples](#examples)
6. [Environment Variables](./ENVIRONMENT.md) 6. [Environment Variables](./ENVIRONMENT.md)
7. [Release Notes](./CHANGELOG.md) 7. [Documentation][documentation::web]
8. [Release Notes](./CHANGELOG.md)
## Included Services ## Included Services
@ -59,7 +62,8 @@ A fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.)
### Available image sources / tags ### Available image sources / tags
The [CI/CD workflows](https://github.com/docker-mailserver/docker-mailserver/actions) automatically build, test and push new images to container registries. Currently, the following registries are supported: [CI/CD](https://github.com/docker-mailserver/docker-mailserver/actions) will automatically build, test and push new images to container registries. Currently, the following registries are supported:
- [DockerHub](https://hub.docker.com/repository/docker/mailserver/docker-mailserver) - [DockerHub](https://hub.docker.com/repository/docker/mailserver/docker-mailserver)
- [GitHub Container Registry](https://github.com/orgs/docker-mailserver/packages?repo_name=docker-mailserver) - [GitHub Container Registry](https://github.com/orgs/docker-mailserver/packages?repo_name=docker-mailserver)
@ -69,8 +73,7 @@ All workflows are using the **tagging convention** listed below. It is subsequen
|--------------|-----------------------|------------|-------------------------------| |--------------|-----------------------|------------|-------------------------------|
| `push` | `refs/heads/master` | `cf20257` | `edge` | | `push` | `refs/heads/master` | `cf20257` | `edge` |
| `push` | `refs/heads/stable` | `cf20257` | `stable` | | `push` | `refs/heads/stable` | `cf20257` | `stable` |
| `push tag` | `refs/tags/1.2.3` | `ad132f5` | `1.2.3`, `1.2`, `1`, `latest` | | `push tag` | `refs/tags/[v]1.2.3` | `ad132f5` | `1.2.3`, `1.2`, `1`, `latest` |
| `push tag` | `refs/tags/v1.2.3` | `ad132f5` | `1.2.3`, `1.2`, `1`, `latest` |
### Get the tools ### Get the tools
@ -117,15 +120,10 @@ If you'd like to use SELinux, add `-Z` to the variable `SELINUX_LABEL` in `.env`
``` BASH ``` BASH
docker-compose up -d mailserver docker-compose up -d mailserver
# without SELinux # for SELinux, use -Z
./setup.sh email add <user@domain> [<password>] ./setup.sh [-Z] email add <user@domain> [<password>]
./setup.sh alias add postmaster@<domain> <user@domain> ./setup.sh [-Z] alias add postmaster@<domain> <user@domain>
./setup.sh config dkim ./setup.sh [-Z] config dkim
# with SELinux
./setup.sh -Z email add <user@domain> [<password>]
./setup.sh -Z alias add postmaster@<domain> <user@domain>
./setup.sh -Z config dkim
``` ```
If you're seeing error messages about unchecked error, please **verify that you're using the right version of `setup.sh`**. Refer to the [Get the tools](#get-the-tools) section and / or execute `./setup.sh help` and read the `VERSION` section. If you're seeing error messages about unchecked error, please **verify that you're using the right version of `setup.sh`**. Refer to the [Get the tools](#get-the-tools) section and / or execute `./setup.sh help` and read the `VERSION` section.
@ -142,45 +140,11 @@ If you want to see detailed usage information, run `./setup.sh config dkim help`
#### DNS - DKIM #### DNS - DKIM
When keys are generated, you can configure your DNS server by just pasting the content of `config/opendkim/keys/domain.tld/mail.txt` to [set up DKIM](https://mxtoolbox.com/dmarc/dkim/setup/how-to-setup-dkim). When keys are generated, you can configure your DNS server by just pasting the content of `config/opendkim/keys/domain.tld/mail.txt` to [set up DKIM](https://mxtoolbox.com/dmarc/dkim/setup/how-to-setup-dkim). See the [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/best-practices/dkim/) for more details.
#### Custom user changes & patches #### Custom user changes & patches
If you'd like to change, patch or alter files or behavior of `docker-mailserver`, you can use a script. Just place it the `config/` folder that is created on startup and call it `user-patches.sh`. The setup is done like this: If you'd like to change, patch or alter files or behavior of `docker-mailserver`, you can use a script. See the [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/advanced/user-patches/) for a detailed explanation.
``` BASH
# 1. Either create the config/ directory yourself
# or let docker-mailserver create it on initial
# startup
/where/docker-mailserver/resides/ $ mkdir config && cd config
# 2. Create the user-patches.sh script and make it
# executable
/where/docker-mailserver/resides/config/ $ touch user-patches.sh
/where/docker-mailserver/resides/config/ $ chmod +x user-patches.sh
# 3. Edit it
/where/docker-mailserver/resides/config/ $ vi user-patches.sh
/where/docker-mailserver/resides/config/ $ cat user-patches.sh
#! /bin/bash
# ! THIS IS AN EXAMPLE !
# If you modify any supervisord configuration, make sure
# to run `supervisorctl update` and/or `supervisorctl reload` afterwards.
# shellcheck source=/dev/null
. /usr/local/bin/helper-functions.sh
_notify 'Applying user-patches'
if ! grep -q '192.168.0.1' /etc/hosts
then
echo -e '192.168.0.1 some.domain.com' >> /etc/hosts
fi
```
And you're done. The user patches script runs right before starting daemons. That means, all the other configuration is in place, so the script can make final adjustments.
#### Supported Operating Systems #### Supported Operating Systems
@ -210,20 +174,9 @@ You're done! And don't forget to have a look at the remaining functions of the `
If you got any problems with SPF and/or forwarding mails, give [SRS](https://github.com/roehling/postsrsd/blob/master/README.md) a try. You enable SRS by setting `ENABLE_SRS=1`. See the variable description for further information. If you got any problems with SPF and/or forwarding mails, give [SRS](https://github.com/roehling/postsrsd/blob/master/README.md) a try. You enable SRS by setting `ENABLE_SRS=1`. See the variable description for further information.
#### Exposed ports #### Ports
| Protocol | Opt-in Encryption &#185; | Enforced Encryption | Purpose | See the [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/security/understanding-the-ports/) for further details and best practice advice, **especially regarding security concerns**.
| :------: | :----------------------: | :-----------------: | :------------: |
| SMTP | 25 | N/A | Transfer&#178; |
| ESMTP | 587 | 465&#179; | Submission |
| POP3 | 110 | 995 | Retrieval |
| IMAP4 | 143 | 993 | Retrieval |
1. A connection *may* be secured over TLS when both ends support `STARTTLS`. On ports 110, 143 and 587, `docker-mailserver` will reject a connection that cannot be secured. Port 25 is [required](https://serverfault.com/questions/623692/is-it-still-wrong-to-require-starttls-on-incoming-smtp-messages) to support insecure connections.
2. Receives email and filters for spam and viruses. For submitting outgoing mail you should prefer the submission ports(465, 587), which require authentication. Unless a relay host is configured, outgoing email will leave the server via port 25(thus outbound traffic must not be blocked by your provider or firewall).
3. A submission port since 2018, [RFC 8314](https://tools.ietf.org/html/rfc8314). Originally a secure variant of port 25.
See the [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/security/understanding-the-ports/) for further details and best practice advice, especially regarding security concerns.
## Examples ## Examples

43
docs/content/config/advanced/override-defaults/user-patches.md Normal file
View file

@ -0,0 +1,43 @@
---
title: 'Custom User Changes & Patches | Scripting'
---
If you'd like to change, patch or alter files or behavior of `docker-mailserver`, you can use a script.
In case you cloned this repository, you can copy the file `user-patches.sh.dist` under `config/` with `#!sh cp config/user-patches.sh.dist config/user-patches.sh` in order to create the `user-patches.sh` script. In case you are managing your directory structure yourself, create a `config/` directory and the `user-patches.sh` file yourself.
``` sh
# 1. Either create the config/ directory yourself
# or let docker-mailserver create it on initial
# startup
~/somewhere $ mkdir config && cd config
# 2. Create the user-patches.sh and edit it
~/somewhere/config $ touch user-patches.sh
~/somewhere/config $ vi user-patches.sh
```
The contents could look like this
``` sh
#! /bin/bash
sed -i -E 's|(log_level).*|\1 = -1;|g' /etc/amavis/conf.d/49-docker-mailserver
cat >/etc/amavis/conf.d/50-user << "END"
use strict;
$undecipherable_subject_tag = undef;
$admin_maps_by_ccat{+CC_UNCHECKED} = undef;
#------------ Do not modify anything below this line -------------
1; # ensure a defined return
END
...
```
And you're done. The user patches script runs right before starting daemons. That means, all the other configuration is in place, so the script can make final adjustments.
!!! note
Many "patches" can already be done with the Docker Compose-/Stack-file. Adding hostnames to `/etc/hosts` is done with the `#!yaml extra_hosts:` section, `sysctl` commands can be managed with the `#!yaml sysctls:` section, etc.

4
docs/content/index.md
View file

@ -18,6 +18,9 @@ This documentation provides you with advanced configuration, detailed examples,
!!! tip !!! tip
See the [FAQ][docs-faq] for some more tips! See the [FAQ][docs-faq] for some more tips!
!!! important
If you'd like to change, patch or alter files or behavior of `docker-mailserver`, you can use a script. Just place it in the `config/` folder that is created on startup and call it `user-patches.sh`. If you'd like to see the full documentation and an example, visit the ['Modifications via Script' page][docs-userpatches].
## Contributing ## Contributing
We are always happy to welcome new contributors. For guidelines and entrypoints please have a look at the [Contributing section][docs-contributing]. We are always happy to welcome new contributors. For guidelines and entrypoints please have a look at the [Contributing section][docs-contributing].
@ -26,6 +29,7 @@ We are always happy to welcome new contributors. For guidelines and entrypoints
[docs-faq]: ./faq.md [docs-faq]: ./faq.md
[docs-optionalconfig]: ./config/advanced/optional-config.md [docs-optionalconfig]: ./config/advanced/optional-config.md
[docs-setupsh]: ./config/setup.sh.md [docs-setupsh]: ./config/setup.sh.md
[docs-userpatches]: ./config/advanced/override-defaults/user-patches.md
[github-file-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md [github-file-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md
[github-file-env]: https://github.com/docker-mailserver/docker-mailserver/blob/master/ENVIRONMENT.md [github-file-env]: https://github.com/docker-mailserver/docker-mailserver/blob/master/ENVIRONMENT.md
[github-file-setupsh]: https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh [github-file-setupsh]: https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh

2
docs/mkdocs.yml
View file

@ -55,6 +55,7 @@ markdown_extensions:
- pymdownx.details - pymdownx.details
- pymdownx.superfences - pymdownx.superfences
- pymdownx.magiclink - pymdownx.magiclink
- pymdownx.inlinehilite
- pymdownx.emoji: - pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg emoji_generator: !!python/name:materialx.emoji.to_svg
@ -109,6 +110,7 @@ nav:
- 'Override the Default Configs': - 'Override the Default Configs':
- 'Dovecot': config/advanced/override-defaults/dovecot.md - 'Dovecot': config/advanced/override-defaults/dovecot.md
- 'Postfix': config/advanced/override-defaults/postfix.md - 'Postfix': config/advanced/override-defaults/postfix.md
- 'Modifications via Script': config/advanced/override-defaults/user-patches.md
- 'LDAP Authentication': config/advanced/auth-ldap.md - 'LDAP Authentication': config/advanced/auth-ldap.md
- 'Email Filtering with Sieve': config/advanced/mail-sieve.md - 'Email Filtering with Sieve': config/advanced/mail-sieve.md
- 'Email Gathering with Fetchmail': config/advanced/mail-fetchmail.md - 'Email Gathering with Fetchmail': config/advanced/mail-fetchmail.md