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

docs: Revise basic-install.md (#2210)

Browse source 
This was a community contributed guide from the Github Wiki prior to docs migration. I've rewritten it by restructuring the content, introducing numerical steps and revising some of the content, while removing third-party software that was unnecessary (the original authors and content related to their use-case, Moodle).

See the PR for further details and reference links regarding the original documents history.

The PR provides improved diff via separate commits scoping changes at the correct change bounds, unfortunately the full diff doesn't align to those boundaries well making it more difficult to review vs individual commits.
This commit is contained in:
Brennan Kinney 2021-09-27 12:46:46 +13:00 committed by GitHub
parent 4f91620a7f
commit b86645fbe5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 90 additions and 103 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

193
docs/content/examples/tutorials/basic-installation.md
View file

@ -2,25 +2,23 @@
title: 'Tutorials | Basic Installation'
---
## Building a Simple Mail-Server
## Setting up 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].
This is a community contributed guide. Please let us know via a Github Issue if you're having any difficulty following the guide so that we can update it.
We are going to use this docker based mailserver:
This guide is focused on only using [SMTP ports (not POP3 and IMAP)][docs-ports] with the intent to send received mail to another MTA service such as _Gmail_. It is not intended to have a MUA client (_eg: Thunderbird_) to retrieve mail directly from `docker-mailserver` via POP3/IMAP.
- First create a directory for `docker-mailserver` to store data in, and get the `setup.sh` script:
In this setup `docker-mailserver` is not intended to receive email externally, so no anti-spam or anti-virus software is needed, making the service lighter to run.
```sh
mkdir -p /var/ds/mail.example.com
cd /var/ds/mail.example.com/
!!! warning "Open Relays"
curl -o setup.sh \
https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/setup.sh
chmod a+x ./setup.sh
```
Adding the docker network's gateway to the list of trusted hosts (_eg: 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].
- Create the file `docker-compose.yml` with a content like this:
1. If you're running a version of `docker-mailserver` earlier than v10.2, [you'll need to get `setup.sh`][docs-setup-script]. Otherwise you can substitute `./setup.sh <command>` with `docker exec mailserver setup <command>`.
2. Pull the docker image: `docker pull docker.io/mailserver/docker-mailserver:latest`.
3. Create the file `docker-compose.yml` with a content like this:
!!! example
@ -32,65 +30,56 @@ We are going to use this docker based mailserver:
image: docker.io/mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail
# Change this to your domain, it is used for your email accounts (eg: user@example.com):
domainname: example.com
ports:
- "25:25"
- "587:587"
- "465:465"
- "25:25"
- "587:587"
- "465:465"
volumes:
- ./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
- /var/ds/wsproxy/letsencrypt/:/etc/letsencrypt/
- ./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/
# The "from" path will vary based on where your certs are locally:
- ./docker-data/nginx-proxy/certs/:/etc/letsencrypt/
- /etc/localtime:/etc/localtime:ro
environment:
- PERMIT_DOCKER=network
- SSL_TYPE=letsencrypt
- ONE_DIR=1
- DMS_DEBUG=0
- SPOOF_PROTECTION=0
- REPORT_RECIPIENT=1
- ENABLE_SPAMASSASSIN=0
- ENABLE_CLAMAV=0
- ENABLE_FAIL2BAN=1
- ENABLE_POSTGREY=0
- ENABLE_FAIL2BAN=1
# Using letsencrypt for SSL/TLS certificates
- SSL_TYPE=letsencrypt
# Allow sending emails from other docker containers
# Beware creating an Open Relay: https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/#permit_docker
- PERMIT_DOCKER=network
# All env below are default settings:
- DMS_DEBUG=0
- ONE_DIR=1
- ENABLE_POSTGREY=0
- ENABLE_CLAMAV=0
- ENABLE_SPAMASSASSIN=0
# You may want to enable this: https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/#spoof_protection
# See step 8 below, which demonstrates setup with enabled/disabled SPOOF_PROTECTION:
- SPOOF_PROTECTION=0
cap_add:
- NET_ADMIN
- SYS_PTRACE
- NET_ADMIN # For Fail2Ban to work
- SYS_PTRACE
```
For more details about the environment variables that can be used, and their meaning and possible values, check also these:
- The docs have a detailed page on [Environment Variables][docs-environment] for reference.
- [Environment Variables][docs-environment]
- [`mailserver.env` file][github-file-dotenv]
!!! note "Firewalled ports"
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:
You may need to open ports `25`, `587` and `465` on the firewall. For example, with the firewall `ufw`, run:
- `PERMIT_DOCKER=network` because we want to send emails from other docker containers.
- `SSL_TYPE=letsencrypt` because we will manage SSL certificates with letsencrypt.
```sh
ufw allow 25
ufw allow 587
ufw allow 465
```
- We need to open ports `25`, `587` and `465` on the firewall:
4. Configure your DNS service to use an MX record for the _hostname_ (eg: `mail`) you configured in the previous step and add the [SPF][docs-spf] TXT record.
```sh
ufw allow 25
ufw allow 587
ufw allow 465
```
On your server you may have to do it differently.
- 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 `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.com
```
- Add these configurations as well on the same file on the DNS server:
If you manually manage the DNS zone file for the domain, it would look something like this:
```txt
mail IN A 10.11.12.13
@ -104,61 +93,59 @@ We are going to use this docker based mailserver:
Then don't forget to change the serial number and to restart the service.
- Get an SSL certificate from letsencrypt. I use [wsproxy](https://gitlab.com/docker-scripts/wsproxy) for managing SSL letsencrypt certificates of my domains:
5. [Generate DKIM keys][docs-dkim] for your domain via `./setup.sh config dkim`.
```sh
cd /var/ds/wsproxy
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
Copy the content of the file `docker-data/dms/config/opendkim/keys/example.com/mail.txt` and add it to your DNS records as a TXT like SPF was handled above.
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.com
```
Now the certificates will be available on `/var/ds/wsproxy/letsencrypt/live/mail.example.com`.
6. Get an SSL certificate, [we have a guide for you here][docs-ssl] (_Let's Encrypt_ is a popular service to get free SSL certificates).
- Start `docker-mailserver` and check for any errors:
7. Start `docker-mailserver` and check the terminal output for any errors: `docker-compose up`.
```sh
apt install docker-compose
docker-compose up mailserver
```
8. Create email accounts and aliases:
- Create email accounts and aliases with `SPOOF_PROTECTION=0`:
!!! example "With `SPOOF_PROTECTION=0`"
```sh
./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
```
```sh
./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 mail-server lighter.
Aliases make sure that any email that comes to these accounts is forwarded to your third-party email address (`external-account@gmail.com`), where they are retrieved (_eg: via third-party web or mobile app_), instead of connecting directly to `docker-mailserer` with POP3 / IMAP.
- Or create email accounts and aliases with `SPOOF_PROTECTION=1`:
!!! example "With `SPOOF_PROTECTION=1`"
```sh
./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
```
```sh
./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.com` and `info.gmail@example.com` )
This extra step is required to avoid the `553 5.7.1 Sender address rejected: not owned by user` error (_the accounts used for submitting mail to Gmail are `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 mailserver`.
- Now save on Moodle configuration the SMTP settings and test by trying to send some messages to other users:
- **SMTP hosts**: `mail.example.com:465`
- **SMTP security**: `SSL`
- **SMTP username**: `info@example.com`
- **SMTP password**: `passwd123`
9. Send some test emails to these addresses and make other tests. Once everything is working well, stop the container with `ctrl+c` and start it again as a daemon: `docker-compose up -d`.
[docs-ports]: ../../config/security/understanding-the-ports.md
[docs-setup-script]: ../../config/setup.sh.md
[docs-environment]: ../../config/environment.md
[github-file-dotenv]: https://github.com/docker-mailserver/docker-mailserver/blob/master/mailserver.env
[docs-spf]: ../../config/best-practice/spf.md
[docs-dkim]: ../../config/best-practice/dkim.md
[docs-ssl]: ../../config/security/ssl.md#lets-encrypt-recommended
[github-issue-1405-comment]: https://github.com/docker-mailserver/docker-mailserver/issues/1405#issuecomment-590106498