docker
/
docker-mailserver
mirror of https://github.com/tomav/docker-mailserver.git
1
0
Fork 0
Code Issues Releases Wiki Activity

docs: update docs that cite compose files (#3234)

This commit is contained in:
Georg Lauterbach 2023-04-09 11:42:50 +02:00 committed by GitHub
parent 2b7cab28f7
commit fedc3b3ee0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 37 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/content/config/advanced/full-text-search.md
View File

@ -58,13 +58,11 @@ While indexing is memory intensive, you can configure the plugin to limit the am
2. Update `docker-compose.yml` to load the previously created dovecot plugin config file:
```yaml
version: '3.8'
services:
mailserver:
image: ghcr.io/docker-mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail
domainname: example.com
hostname: mail.example.com
env_file: mailserver.env
ports:
- "25:25" # SMTP (explicit TLS => STARTTLS)

8
docs/content/config/advanced/ipv6.md
View File

@ -12,11 +12,7 @@ This can be solved by supporting IPv6 connections all the way to the `docker-mai
```diff
+++ b/serv/docker-compose.yml
@@ -1,4 +1,4 @@
-version: '2'
+version: '2.1'
@@ -32,6 +32,16 @@ services:
@@ ... @@ services:
+ ipv6nat:
+ image: robbertkl/ipv6nat
@ -29,7 +25,7 @@ This can be solved by supporting IPv6 connections all the way to the `docker-mai
+ - /var/run/docker.sock:/var/run/docker.sock:ro
+ - /lib/modules:/lib/modules:ro
@@ -306,4 +316,13 @@ networks:
@@ ... @@ networks:
+ default:
+ driver: bridge

6
docs/content/config/environment.md
View File

@ -10,8 +10,10 @@ title: Environment Variables
##### OVERRIDE_HOSTNAME
- **empty** => uses the `hostname` command to get canonical hostname for `docker-mailserver` to use.
- => Specify a fully-qualified domainname to serve mail for. This is used for many of the config features so if you can't set your hostname (_eg: you're in a container platform that doesn't let you_) specify it via this environment variable. It will take priority over `docker run` options: `--hostname` and `--domainname`, or `docker-compose.yml` config equivalents: `hostname:` and `domainname:`.
If you can't set your hostname (_eg: you're in a container platform that doesn't let you_) specify it via this environment variable. It will have priority over `docker run --hostname`, or the equivalent `hostname:` field in `docker-compose.yml`.
- **empty** => Uses the `hostname -f` command to get canonical hostname for `docker-mailserver` to use.
- => Specify an FQDN (fully-qualified domain name) to serve mail for. The hostname is required for `docker-mailserver` to function correctly.
##### LOG_LEVEL

85
docs/content/config/security/ssl.md
View File

@ -27,43 +27,29 @@ After installation, you can test your setup with:
An [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) (_Fully Qualified Domain Name_) such as `mail.example.com` is required for `docker-mailserver` to function correctly, especially for looking up the correct SSL certificate to use.
Internally, `hostname -f` will be used to retrieve the FQDN as configured in the below examples.
- `mail.example.com` will still use `user@example.com` as the mail address. You do not need a bare domain for that.
- We usually discourage assigning a bare domain (_When your DNS MX record does not point to a subdomain_) to represent `docker-mailserver`. However, an FQDN of [just `example.com` is also supported][docs-faq-baredomain].
- Internally, `hostname -f` will be used to retrieve the FQDN as configured in the below examples.
- Wildcard certificates (eg: `*.example.com`) are supported for `SSL_TYPE=letsencrypt`. Your configured FQDN below may be `mail.example.com`, and your wildcard certificate provisioned to `/etc/letsencrypt/live/example.com` which will be checked as a fallback FQDN by `docker-mailserver`.
Wildcard certificates (eg: `*.example.com`) are supported for `SSL_TYPE=letsencrypt`. Your configured FQDN below may be `mail.example.com`, and your wildcard certificate provisioned to `/etc/letsencrypt/live/example.com` which will be checked as a fallback FQDN by `docker-mailserver`.
!!! example "Setting the hostname correctly"
!!! example "Docker CLI options `--hostname` and optionally `--domainname`"
Change `mail.example.com` below to your own FQDN.
```sh
docker run --hostname mail --domainname example.com
# `--domainname` is not required:
# CLI:
docker run --hostname mail.example.com
```
!!! example "`docker-compose.yml` config"
or
```yml
services:
mailserver:
hostname: mail
domainname: example.com
# `domainname` is not required:
# docker-compose.yml
services:
mailserver:
hostname: mail.example.com
```
!!! example "_Bare domains_ (eg: `example.com`) should only use the hostname option"
```sh
docker run --hostname example.com
```
```yml
services:
mailserver:
hostname: example.com
```
## Provisioning methods
### Let's Encrypt (Recommended)
@ -91,9 +77,7 @@ You don't have to do anything else. Enjoy!
```yaml
services:
mailserver:
# For the FQDN 'mail.example.com':
hostname: mail
domainname: example.com
hostname: mail.example.com
environment:
- SSL_TYPE=letsencrypt
volumes:
@ -107,7 +91,6 @@ Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store the
1. Getting a certificate is this simple! (_Referencing: [Certbot docker instructions][certbot::docker] and [`certonly --standalone` mode][certbot::standalone]_):
```sh
# Change `mail.example.com` below to your own FQDN.
# Requires access to port 80 from the internet, adjust your firewall if needed.
docker run --rm -it \
-v "${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/" \
@ -125,9 +108,7 @@ Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store the
```yaml
services:
mailserver:
# For the FQDN 'mail.example.com':
hostname: mail
domainname: example.com
hostname: mail.example.com
environment:
- SSL_TYPE=letsencrypt
volumes:
@ -367,7 +348,6 @@ The following example is the [basic setup][acme-companion::basic-setup] you need
You should have an existing `docker-compose.yml` with a `mailserver` service. Below are the modifications to add for integrating with `nginx-proxy` and `acme-companion` services:
```yaml
version: '3.8'
services:
# Add the following `environment` and `volumes` to your existing `mailserver` service:
mailserver:
@ -395,12 +375,10 @@ The following example is the [basic setup][acme-companion::basic-setup] you need
volumes:
# `certs/`: Managed by the `acme-companion` container (_read-only_).
# `docker.sock`: Required to interact with containers via the Docker API.
# `dhparam`: A named data volume to prevent `nginx-proxy` creating an anonymous volume each time.
- ./docker-data/nginx-proxy/html/:/usr/share/nginx/html/
- ./docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/
- ./docker-data/acme-companion/certs/:/etc/nginx/certs/:ro
- /var/run/docker.sock:/tmp/docker.sock:ro
- dhparam:/etc/nginx/dhparam
acme-companion:
image: nginxproxy/acme-companion
@ -421,12 +399,6 @@ The following example is the [basic setup][acme-companion::basic-setup] you need
- ./docker-data/acme-companion/certs/:/etc/nginx/certs/:rw
- ./docker-data/acme-companion/acme-state/:/etc/acme.sh/
- /var/run/docker.sock:/var/run/docker.sock:ro
# Once `nginx-proxy` fixes their Dockerfile, this named data volume can be removed from docs.
# Users can opt for a local bind mount volume like all others if they prefer, but this volume
# is only intended to be temporary.
volumes:
dhparam:
```
!!! tip "Optional ENV vars worth knowing about"
@ -494,8 +466,6 @@ Amongst other things, you can use these to secure your mail-server. DSM locates
Navigate to that folder and note the 6 character random folder name of the certificate you'd like to use. Then, add the following to your `docker-compose.yml` declaration file:
```yaml
# Note: If you have an existing setup that was working pre docker-mailserver v10.2,
# '/tmp/dms/custom-certs' below has replaced the previous '/tmp/ssl' container path.
volumes:
- /usr/syno/etc/certificate/_archive/<your-folder>/:/tmp/dms/custom-certs/
environment:
@ -508,16 +478,6 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
### Caddy
If you are using Caddy to renew your certificates, please note that only RSA certificates work. Read [#1440][github-issue-1440] for details. In short for Caddy v1 the `Caddyfile` should look something like:
```caddyfile
https://mail.example.com {
tls admin@example.com {
key_type rsa2048
}
}
```
For Caddy v2 you can specify the `key_type` in your server's global settings, which would end up looking something like this if you're using a `Caddyfile`:
```caddyfile
@ -533,7 +493,7 @@ For Caddy v2 you can specify the `key_type` in your server's global settings, wh
If you are instead using a json config for Caddy v2, you can set it in your site's TLS automation policies:
???+ example "Example Code"
??? example "Caddy v2 JSON example snippet"
```json
{
@ -600,7 +560,7 @@ If you are instead using a json config for Caddy v2, you can set it in your site
}
```
The generated certificates can be mounted:
The generated certificates can then be mounted:
```yaml
volumes:
@ -608,15 +568,6 @@ volumes:
- ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.key:/etc/letsencrypt/live/mail.example.com/privkey.pem
```
EC certificates fail in the TLS handshake:
```log
CONNECTED(00000003)
140342221178112:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure:ssl/record/rec_layer_s3.c:1543:SSL alert number 40
no peer certificate available
No client certificate CA names sent
```
### Traefik v2
[Traefik][traefik::github] is an open-source application proxy using the [ACME protocol][ietf::rfc::acme]. [Traefik][traefik::github] can request certificates for domains and subdomains, and it will take care of renewals, challenge negotiations, etc. We strongly recommend to use [Traefik][traefik::github]'s major version 2.
@ -637,13 +588,11 @@ This setup only comes with one caveat: The domain has to be configured on anothe
Here is an example setup for [`docker-compose`](https://docs.docker.com/compose/):
```yaml
version: '3.8'
services:
mailserver:
image: ghcr.io/docker-mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail
domainname: example.com
hostname: mail.example.com
volumes:
- ./docker-data/traefik/acme.json:/etc/letsencrypt/acme.json:ro
environment:
@ -927,10 +876,10 @@ Despite this, if you must use non-standard DH parameters or you would like to sw
[docs-env::ssl-type]: ../environment.md#ssl_type
[docs-optional-config]: ../advanced/optional-config.md
[docs-faq-baredomain]: ../../faq.md#can-i-use-a-nakedbare-domain-ie-no-hostname
[github-file-compose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/docker-compose.yml
[github-file::tls-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/3b8059f2daca80d967635e04d8d81e9abb755a4d/test/test-files/ssl/example.test/README.md
[github-issue-1440]: https://github.com/docker-mailserver/docker-mailserver/issues/1440
[hanscees-renewcerts]: https://github.com/hanscees/dockerscripts/blob/master/scripts/tomav-renew-certs
[traefik::github]: https://github.com/containous/traefik

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

@ -30,7 +30,6 @@ Feel free to add your configuration if you achieved the same goal using differen
Truncated configuration of traefik itself:
```yaml
version: '3.8'
services:
reverse-proxy:
image: docker.io/traefik:latest # v2.5
@ -57,13 +56,11 @@ Feel free to add your configuration if you achieved the same goal using differen
Truncated list of necessary labels on the `docker-mailserver` container:
```yaml
version: '3.8'
services:
mailserver:
image: ghcr.io/docker-mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail
domainname: example.com
hostname: mail.example.com
restart: always
networks:
- proxy

16
docs/content/faq.md
View File

@ -168,7 +168,7 @@ To use a bare domain (_where the host name is `example.com` and the domain is al
- From: `mydestination = $myhostname, localhost.$mydomain, localhost`
- To: `mydestination = localhost.$mydomain, localhost`
Add the latter line to `docker-data/dms/config/postfix-main.cf`. If that doesn't work, make sure that `OVERRIDE_HOSTNAME` is blank in your `mailserver.env` file (see [#1731](https://github.com/docker-mailserver/docker-mailserver/issues/1731#issuecomment-753968425)). Without these changes there will be warnings in the logs like:
Add the latter line to `docker-data/dms/config/postfix-main.cf`. If that doesn't work, make sure that [`OVERRIDE_HOSTNAME` is blank in your `mailserver.env` file][github-comment-override-hostname]. Without these changes there will be warnings in the logs like:
```log
warning: do not list domain example.com in BOTH mydestination and virtual_mailbox_domains
@ -176,7 +176,15 @@ warning: do not list domain example.com in BOTH mydestination and virtual_mailbo
Plus of course mail delivery fails.
Also you need to define `hostname: example.com` in your docker-compose.yml and don't sepecify the `domainname:` at all.
Also you need to define `hostname: example.com` in your `docker-compose.yml`.
!!! tip "You might not want a bare domain"
We encourage you to consider using a subdomain where possible.
- There are [benefits][github-comment-baredomain] to preferring a subdomain.
- A bare domain is not required to have `user@example.com`, that is distinct from your hostname which is identified by a DNS MX record.
### How can I configure a catch-all?
@ -453,8 +461,6 @@ The following configuration works nicely:
Or with [Docker Swarm](https://docs.docker.com/engine/swarm/configs/):
```yaml
version: '3.8'
services:
mailserver:
image: ghcr.io/docker-mailserver/docker-mailserver:latest
@ -519,6 +525,8 @@ $spam_quarantine_to = "amavis\@example.com";
[fail2ban-customize]: ./config/security/fail2ban.md
[docs-maintenance]: ./config/advanced/maintenance/update-and-cleanup.md
[docs-userpatches]: ./config/advanced/override-defaults/user-patches.md
[github-comment-baredomain]: https://github.com/docker-mailserver/docker-mailserver/issues/3048#issuecomment-1432358353
[github-comment-override-hostname]: https://github.com/docker-mailserver/docker-mailserver/issues/1731#issuecomment-753968425
[github-issue-95]: https://github.com/docker-mailserver/docker-mailserver/issues/95
[github-issue-97]: https://github.com/docker-mailserver/docker-mailserver/issues/97
[github-issue-1247]: https://github.com/docker-mailserver/docker-mailserver/issues/1247