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

completely refactor README & parts of docs (#3097) 

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
This commit is contained in:
Georg Lauterbach 2023-02-19 13:25:14 +01:00 committed by GitHub
parent bee9e3627d
commit 853301338c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 551 additions and 543 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

320
README.md
View File

@ -9,313 +9,41 @@
[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 production-ready 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](#usage) and upgrade. [Documentation][documentation::web] via MkDocs.
## :page_with_curl: About
Originally created by @tomav, docker-mailserver is now maintained by volunteers since January 2021.
A production-ready fullstack but simple containerized mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.). Only configuration files, no SQL database. Keep it simple and versioned. Easy to deploy and upgrade. Originally created by @tomav, this project is now maintained by volunteers since January 2021.
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.
## :bulb: Documentation
1. [Included Services](#included-services)
2. [Issues and Contributing](https://docker-mailserver.github.io/docker-mailserver/edge/contributing/issues-and-pull-requests/)
3. [Requirements](#requirements)
4. [Usage](#usage)
5. [Examples](#examples)
We provide a [dedicated documentation][documentation::web] hosted on GitHub Pages. Make sure to read it as it contains all the information necessary to set up and configure your mail server. The documentation is crafted with Markdown & [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
## :boom: Issues
If you have issues, please search through [the documentation][documentation::web] **for your version** before opening an issue. The issue tracker is for issues, not for personal support. Make sure the version of the documentation matches the image version you're using!
## :link: Links to Useful Resources
1. [FAQ](https://docker-mailserver.github.io/docker-mailserver/edge/faq/)
2. [Usage](https://docker-mailserver.github.io/docker-mailserver/edge/usage/)
3. [Examples](https://docker-mailserver.github.io/docker-mailserver/edge/examples/tutorials/basic-installation/)
4. [Issues and Contributing](https://docker-mailserver.github.io/docker-mailserver/edge/contributing/issues-and-pull-requests/)
5. [Release Notes](./CHANGELOG.md)
6. [Environment Variables](https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/)
7. [Documentation][documentation::web]
8. [Release Notes](./CHANGELOG.md)
7. [Updating](https://docker-mailserver.github.io/docker-mailserver/edge/faq/#updating)
## Included Services
## :package: Included Services
- [Postfix](http://www.postfix.org) with SMTP or LDAP auth
- [Dovecot](https://www.dovecot.org) for SASL, IMAP (or POP3), with LDAP Auth, Sieve and [quotas](https://docker-mailserver.github.io/docker-mailserver/edge/config/user-management/accounts#notes)
- [Postfix](http://www.postfix.org) with SMTP or LDAP authentication and support for [extension delimiters](http://www.postfix.org/postconf.5.html#recipient_delimiter) (_mail to `you+extension@example.com` delivered to `you@example.com`_)
- [Dovecot](https://www.dovecot.org) with SASL, IMAP, POP3, LDAP, [basic Sieve support](https://docker-mailserver.github.io/docker-mailserver/edge/config/advanced/mail-sieve) and [quotas](https://docker-mailserver.github.io/docker-mailserver/edge/config/user-management/accounts#notes)
- [Rspamd](https://rspamd.com/)
- [Amavis](https://www.amavis.org/)
- [SpamAssassin](http://spamassassin.apache.org/) supporting custom rules
- [ClamAV](https://www.clamav.net/) with automatic updates
- [OpenDKIM](http://www.opendkim.org)
- [OpenDMARC](https://github.com/trusteddomainproject/OpenDMARC)
- [OpenDKIM](http://www.opendkim.org) & [OpenDMARC](https://github.com/trusteddomainproject/OpenDMARC)
- [Fail2ban](https://www.fail2ban.org/wiki/index.php/Main_Page)
- [Fetchmail](http://www.fetchmail.info/fetchmail-man.html)
- [Postscreen](http://www.postfix.org/POSTSCREEN_README.html)
- [Postgrey](https://postgrey.schweikert.ch/)
- [LetsEncrypt](https://letsencrypt.org/) and self-signed certificates
- [Setup script](https://docker-mailserver.github.io/docker-mailserver/edge/config/setup.sh) to easily configure and maintain your mail-server
- Basic [Sieve support](https://docker-mailserver.github.io/docker-mailserver/edge/config/advanced/mail-sieve) using dovecot
- SASLauthd with LDAP auth (please see the note [down below](#ldap-setup))
- Persistent data and state
- [CI/CD](https://github.com/docker-mailserver/docker-mailserver/actions)
- [Extension Delimiters](http://www.postfix.org/postconf.5.html#recipient_delimiter) (`you+extension@example.com` go to `you@example.com`)
## Requirements
**Recommended**:
- 1 Core
- 2GB RAM
- Swap enabled for the container
**Minimum**:
- 1 vCore
- 512MB RAM
- You'll need to deactivate some services like ClamAV to be able to run on a host with 512MB of RAM. Even with 1G RAM you may run into problems without swap, see [FAQ](https://docker-mailserver.github.io/docker-mailserver/edge/faq/#what-system-requirements-are-required-to-run-docker-mailserver-effectively).
## Usage
### Available Images / Tags - Tagging Convention
[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:
1. [DockerHub](https://hub.docker.com/r/mailserver/docker-mailserver)
2. [GitHub Container Registry](https://github.com/orgs/docker-mailserver/packages?repo_name=docker-mailserver)
All workflows are using the tagging convention listed below. It is subsequently applied to all images.
| Event | Image Tags |
|--------------------|-------------------------------|
| `push` on `master` | `edge` |
| `push tag` | `1.2.3`, `1.2`, `1`, `latest` |
### Get the Tools
Since Docker Mailserver `v10.2.0`, **`setup.sh` functionality is included within the container image**. The external convenience script is no longer required if you prefer using `docker exec <CONTAINER NAME> setup <COMMAND>` instead. **If you're new to `docker-mailserver`**, it is recommended to use the script `setup.sh` for convenience.
``` BASH
DMS_GITHUB_URL='https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master'
wget "${DMS_GITHUB_URL}/docker-compose.yml"
wget "${DMS_GITHUB_URL}/mailserver.env"
wget "${DMS_GITHUB_URL}/setup.sh"
chmod a+x ./setup.sh
```
### Create a docker-compose Environment
1. [Install the latest docker-compose](https://docs.docker.com/compose/install/)
2. Edit `docker-compose.yml` to your liking
- substitute `mail` (hostname) and `example.com` (domainname) according to your FQDN
- if you want to use SELinux for the `./docker-data/dms/config/:/tmp/docker-mailserver/` mount, append `-z` or `-Z`
3. Configure the mailserver container to your liking by editing `mailserver.env` ([**Documentation**](https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/)), but keep in mind this `.env` file:
- [_only_ basic `VAR=VAL`](https://docs.docker.com/compose/env-file/) is supported (**do not** quote your values!)
- variable substitution is **not** supported (e.g. :no_entry_sign: `OVERRIDE_HOSTNAME=$HOSTNAME.$DOMAINNAME` :no_entry_sign:)
**Note:** If you're using podman, make sure to read the related [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/advanced/podman/)
### Get up and running
#### First Things First
**Use `docker-compose up / down`, not `docker-compose start / stop`**. Otherwise, the container is not properly destroyed and you may experience problems during startup because of inconsistent state.
You are able to get a full overview of how the configuration works by either running:
1. `./setup.sh help` which includes the options of `setup.sh`.
2. `docker run --rm docker.io/mailserver/docker-mailserver:latest setup help` which provides you with all the information on configuration provided "inside" the container itself.
If no `docker-mailserver` container is running, any `./setup.sh` command will check online for the `:latest` image tag (the current _stable_ release), performing a `docker pull ...` if necessary followed by running the command in a temporary container.
``` CONSOLE
$ ./setup.sh help
Image 'docker.io/mailserver/docker-mailserver:latest' not found. Pulling ...
SETUP(1)
NAME
setup - 'docker-mailserver' Administration & Configuration script
...
$ docker run --rm docker.io/mailserver/docker-mailserver:latest setup help
SETUP(1)
NAME
setup - 'docker-mailserver' Administration & Configuration script
...
```
#### Starting for the first time
On first start, you will need to add at least one email account (unless you're using LDAP). You have two minutes to do so, otherwise DMS will shutdown and restart. You can add accounts with the following two methods:
1. Use `setup.sh`: `./setup.sh email add <user@domain>`
2. Run the command directly in the container: `docker exec -ti <CONTAINER NAME> setup email add <user@domain>`
You can then proceed by creating the postmaster alias and by creating DKIM keys.
``` BASH
docker-compose up -d mailserver
# you may add some more users
# for SELinux, use -Z
./setup.sh [-Z] email add <user@domain> [<password>]
# and configure aliases, DKIM and more
./setup.sh [-Z] alias add postmaster@<domain> <user@domain>
```
### Miscellaneous
#### DNS - DKIM
You can (and you should) generate DKIM keys by running
``` BASH
./setup.sh [-Z] config dkim
```
If you want to see detailed usage information, run
``` BASH
./setup.sh config dkim help
```
In case you're using LDAP, the setup looks a bit different as you do not add user accounts directly. Postfix doesn't know your domain(s) and you need to provide it when configuring DKIM:
``` BASH
./setup.sh config dkim domain '<domain.tld>[,<domain2.tld>]'
```
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
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/override-defaults/user-patches/) for a detailed explanation.
#### Updating `docker-mailserver`
**Make sure to read the [CHANGELOG](https://github.com/docker-mailserver/docker-mailserver/blob/master/CHANGELOG.md)** before updating to new versions, to be prepared for possible breaking changes.
``` BASH
docker-compose pull
docker-compose down
docker-compose up -d mailserver
```
You should see the new version number on startup, for example: `[ TASKLOG ] Welcome to docker-mailserver 10.1.2`.
You're done! And don't forget to have a look at the remaining functions of the `setup.sh` script with `./setup.sh help`.
#### Supported Operating Systems
We are currently providing support for Linux. Windows is _not_ supported and is known to cause problems. Similarly, macOS is _not officially_ supported - but you may get it to work there. In the end, Linux should be your preferred operating system for this image, especially when using this mail-server in production.
#### Bare Domains
If you want to use a bare domain (`hostname` == `domainname`), see [FAQ](https://docker-mailserver.github.io/docker-mailserver/edge/faq#can-i-use-nakedbare-domains-no-host-name).
#### Support for Multiple Domains
`docker-mailserver` supports multiple domains out of the box, so you can do this:
``` BASH
./setup.sh email add user1@docker.example.com
./setup.sh email add user1@mail.example.de
./setup.sh email add user1@server.example.org
```
#### SPF/Forwarding Problems
If you got any problems with SPF and/or forwarding mails, give [SRS](https://github.com/roehling/postsrsd/blob/master/README.rst) a try. You enable SRS by setting `ENABLE_SRS=1`. See the variable description for further information.
#### Ports
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**.
#### Mailboxes (_aka IMAP Folders_)
`INBOX` is setup by default with the special IMAP folders `Drafts`, `Sent`, `Junk` and `Trash`. You can learn how to modify or add your own folders (_including additional special folders like `Archive`_) by visiting our docs page [_Customizing IMAP Folders_][docs-examples-imapfolders] for more information.
[docs-examples-imapfolders]: https://docker-mailserver.github.io/docker-mailserver/edge/examples/use-cases/imap-folders
## Examples
### With Relevant Environmental Variables
This example provides you only with a basic example of what a minimal setup could look like. We **strongly recommend** that you go through the configuration file yourself and adjust everything to your needs. The default [docker-compose.yml](./docker-compose.yml) can be used for the purpose out-of-the-box, see the [usage section](#usage).
``` YAML
version: '3.8'
services:
mailserver:
image: docker.io/mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail
domainname: example.com
ports:
- "25:25"
- "143:143"
- "587:587"
- "993:993"
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
environment:
- ENABLE_SPAMASSASSIN=1
- SPAMASSASSIN_SPAM_TO_INBOX=1
- ENABLE_CLAMAV=1
- ENABLE_FAIL2BAN=1
- ENABLE_POSTGREY=1
- ENABLE_SASLAUTHD=0
- ONE_DIR=1
cap_add:
- NET_ADMIN
restart: always
```
### LDAP Setup
**Note** There are currently no LDAP maintainers. If you encounter issues, please raise them in the issue tracker, but be aware that the core maintainers team will most likely not be able to help you. **We would appreciate and we encourage everyone to actively participate in maintaining LDAP-related code by becoming a maintainer!**
``` YAML
version: '3.8'
services:
mailserver:
image: docker.io/mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail
domainname: example.com
ports:
- "25:25"
- "143:143"
- "587:587"
- "993:993"
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
environment:
- ENABLE_SPAMASSASSIN=1
- SPAMASSASSIN_SPAM_TO_INBOX=1
- ENABLE_CLAMAV=1
- ENABLE_FAIL2BAN=1
- ENABLE_POSTGREY=1
- ONE_DIR=1
- ENABLE_LDAP=1 # with the :edge tag, use ACCOUNT_PROVISIONER
- ACCOUNT_PROVISIONER=LDAP
- LDAP_SERVER_HOST=ldap # your ldap container/IP/ServerName
- LDAP_SEARCH_BASE=ou=people,dc=localhost,dc=localdomain
- LDAP_BIND_DN=cn=admin,dc=localhost,dc=localdomain
- LDAP_BIND_PW=admin
- LDAP_QUERY_FILTER_USER=(&(mail=%s)(mailEnabled=TRUE))
- LDAP_QUERY_FILTER_GROUP=(&(mailGroupMember=%s)(mailEnabled=TRUE))
- LDAP_QUERY_FILTER_ALIAS=(|(&(mailAlias=%s)(objectClass=PostfixBookMailForward))(&(mailAlias=%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE)))
- LDAP_QUERY_FILTER_DOMAIN=(|(&(mail=*@%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE))(&(mailGroupMember=*@%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE))(&(mailalias=*@%s)(objectClass=PostfixBookMailForward)))
- DOVECOT_PASS_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
- DOVECOT_USER_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
- ENABLE_SASLAUTHD=1
- SASLAUTHD_MECHANISMS=ldap
- SASLAUTHD_LDAP_SERVER=ldap
- SASLAUTHD_LDAP_BIND_DN=cn=admin,dc=localhost,dc=localdomain
- SASLAUTHD_LDAP_PASSWORD=admin
- SASLAUTHD_LDAP_SEARCH_BASE=ou=people,dc=localhost,dc=localdomain
- SASLAUTHD_LDAP_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%U))
- POSTMASTER_ADDRESS=postmaster@localhost.localdomain
- POSTFIX_MESSAGE_SIZE_LIMIT=100000000
cap_add:
- NET_ADMIN
restart: always
```
- Support for [LetsEncrypt](https://letsencrypt.org/), manual and self-signed certificates
- A [setup script](https://docker-mailserver.github.io/docker-mailserver/edge/config/setup.sh) for easy configuration and maintenance
- SASLauthd with LDAP authentication

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

@ -2,9 +2,94 @@
title: 'Tutorials | Basic Installation'
---
## Setting up a Simple Mail-Server
## A Basic Example With Relevant Environmental Variables
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.
This example provides you only with a basic example of what a minimal setup could look like. We **strongly recommend** that you go through the configuration file yourself and adjust everything to your needs. The default [docker-compose.yml](https://github.com/docker-mailserver/docker-mailserver/blob/master/docker-compose.yml) can be used for the purpose out-of-the-box, see the [_Usage_ chapter](../../usage.md).
``` YAML
services:
mailserver:
image: docker.io/mailserver/docker-mailserver:latest
container_name: mailserver
# Provide the FQDN of your mail server here (Your DNS MX record should point to this value)
hostname: mail.example.com
ports:
- "25:25"
- "587:587"
- "993:993"
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
environment:
- ENABLE_SPAMASSASSIN=1
- SPAMASSASSIN_SPAM_TO_INBOX=1
- ENABLE_CLAMAV=1
- ENABLE_FAIL2BAN=1
- ENABLE_POSTGREY=1
cap_add:
- NET_ADMIN # For Fail2Ban to work
restart: always
```
## A Basic LDAP Setup
**Note** There are currently no LDAP maintainers. If you encounter issues, please raise them in the issue tracker, but be aware that the core maintainers team will most likely not be able to help you. **We would appreciate and we encourage everyone to actively participate in maintaining LDAP-related code by becoming a maintainer!**
``` YAML
services:
mailserver:
image: docker.io/mailserver/docker-mailserver:latest
container_name: mailserver
# Provide the FQDN of your mail server here (Your DNS MX record should point to this value)
hostname: mail.example.com
ports:
- "25:25"
- "587:587"
- "993:993"
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
environment:
- ENABLE_SPAMASSASSIN=1
- SPAMASSASSIN_SPAM_TO_INBOX=1
- ENABLE_CLAMAV=1
- ENABLE_FAIL2BAN=1
- ENABLE_POSTGREY=1
- ACCOUNT_PROVISIONER=LDAP
- LDAP_SERVER_HOST=ldap # your ldap container/IP/ServerName
- LDAP_SEARCH_BASE=ou=people,dc=localhost,dc=localdomain
- LDAP_BIND_DN=cn=admin,dc=localhost,dc=localdomain
- LDAP_BIND_PW=admin
- LDAP_QUERY_FILTER_USER=(&(mail=%s)(mailEnabled=TRUE))
- LDAP_QUERY_FILTER_GROUP=(&(mailGroupMember=%s)(mailEnabled=TRUE))
- LDAP_QUERY_FILTER_ALIAS=(|(&(mailAlias=%s)(objectClass=PostfixBookMailForward))(&(mailAlias=%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE)))
- LDAP_QUERY_FILTER_DOMAIN=(|(&(mail=*@%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE))(&(mailGroupMember=*@%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE))(&(mailalias=*@%s)(objectClass=PostfixBookMailForward)))
- DOVECOT_PASS_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
- DOVECOT_USER_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
- ENABLE_SASLAUTHD=1
- SASLAUTHD_MECHANISMS=ldap
- SASLAUTHD_LDAP_SERVER=ldap
- SASLAUTHD_LDAP_BIND_DN=cn=admin,dc=localhost,dc=localdomain
- SASLAUTHD_LDAP_PASSWORD=admin
- SASLAUTHD_LDAP_SEARCH_BASE=ou=people,dc=localhost,dc=localdomain
- SASLAUTHD_LDAP_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%U))
- POSTMASTER_ADDRESS=postmaster@localhost.localdomain
cap_add:
- NET_ADMIN # For Fail2Ban to work
restart: always
```
## A Detailed Example
!!! note
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.
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.
@ -23,15 +108,12 @@ In this setup `docker-mailserver` is not intended to receive email externally, s
!!! example
```yaml
version: '3.8'
services:
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
# Provide the FQDN of your mail server here (Your DNS MX record should point to this value)
hostname: mail.example.com
ports:
- "25:25"
- "587:587"
@ -41,8 +123,6 @@ In this setup `docker-mailserver` is not intended to receive email externally, s
- ./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:
- ENABLE_FAIL2BAN=1
@ -51,16 +131,12 @@ In this setup `docker-mailserver` is not intended to receive email externally, s
# 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:
- 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 # For Fail2Ban to work
restart: always
```
- The docs have a detailed page on [Environment Variables][docs-environment] for reference.

461
docs/content/faq.md
View File

@ -4,49 +4,94 @@ title: 'FAQ'
### What kind of database are you using?
None! No database is required. Filesystem is the database.
This image is based on config files that can be persisted using bind mounts (default) or Docker volumes, and as such versioned, backed up and so forth.
None! No database is required. The filesystem is the database. This image is based on config files that can be persisted using bind mounts (default) or Docker volumes, and as such versioned, backed up and so forth.
### Where are emails stored?
Mails are stored in `/var/mail/${domain}/${username}`. Since `v9.0.0` it is possible to add custom `user_attributes` for each accounts to have a different mailbox configuration (See [#1792][github-issue-1792]).
### How to alter the running `docker-mailserver` instance _without_ relaunching the container?
### How are IMAP mailboxes (_aka IMAP Folders_) set up?
`INBOX` is setup by default with the special IMAP folders `Drafts`, `Sent`, `Junk` and `Trash`. You can learn how to modify or add your own folders (_including additional special folders like `Archive`_) by visiting our docs page [_Customizing IMAP Folders_](https://docker-mailserver.github.io/docker-mailserver/edge/examples/use-cases/imap-folders) for more information.
### How do I update DMS?
**Make sure to read the [CHANGELOG](https://github.com/docker-mailserver/docker-mailserver/blob/master/CHANGELOG.md)** before updating to new versions, to be prepared for possible breaking changes.
Then, run the following commands:
``` BASH
docker-compose pull
docker-compose down
docker-compose up -d
```
You should see the new version number on startup, for example: `[ INF ] Welcome to docker-mailserver 11.3.1`. And you're done! Don't forget to have a look at the remaining functions of the `setup.sh` script with `./setup.sh help`.
### Which operating systems are supported?
- Linux is officially supported.
- Windows and macOS are _not_ supported and users and have reported various issues running the image on these hosts.
As you'll realistically be deploying to production on a Linux host, if you are on Windows or macOS and want to run the image locally first, it's advised to do so via a VM guest running Linux if you have issues running DMS on your host system.
### What are the system requirements?
#### Recommended
- 1 vCore
- 2GB RAM
- Swap enabled for the container
#### Minimum
- 1 vCore
- 512MB RAM
- You'll need to avoid running some services like ClamAV (_disabled by default_) to be able to run on a host with 512MB of RAM.
!!! warning
ClamAV can consume a lot of memory, as it reads the entire signature database into RAM.
Current figure is about 850M and growing. If you get errors about ClamAV or amavis failing to allocate memory you need more RAM or more swap and of course docker must be allowed to use swap (not always the case). If you can't use swap at all you may need 3G RAM.
### How to alter a running DMS instance _without_ relaunching the container?
`docker-mailserver` aggregates multiple "sub-services", such as Postfix, Dovecot, Fail2ban, SpamAssassin, etc. In many cases, one may edit a sub-service's config and reload that very sub-service, without stopping and relaunching the whole mail-server.
In order to do so, you'll probably want to push your config updates to your server through a Docker volume (these docs use: `./docker-data/dms/config/:/tmp/docker-mailserver/`), then restart the sub-service to apply your changes, using `supervisorctl`. For instance, after editing fail2ban's config: `supervisorctl restart fail2ban`.
See [supervisorctl's documentation](http://supervisord.org/running.html#running-supervisorctl).
See the [documentation for `supervisorctl`](http://supervisord.org/running.html#running-supervisorctl).
!!! tip
To add, update or delete an email account; there is no need to restart postfix / dovecot service inside the container after using `setup.sh` script.
For more information, see [#1639][github-issue-1639].
### How can I sync container with host date/time? Timezone?
### How can I sync the container and host date/time?
Share the host's [`/etc/localtime`](https://www.freedesktop.org/software/systemd/man/localtime.html) with the `docker-mailserver` container, using a Docker volume:
Share the host's [`/etc/localtime`](https://www.freedesktop.org/software/systemd/man/localtime.html) with the container, e.g. by using a bind mount:
```yaml
volumes:
- /etc/localtime:/etc/localtime:ro
```
!!! help "Optional"
Add one line to `.env` or `env-mailserver` to set timetzone for container, for example:
```env
TZ=Europe/Berlin
```
Check here for the [`tz name list`](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
Optionally, you can set the `TZ` ENV variable; e.g. `TZ=Europe/Berlin`. Check [this list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for which values are allowed.
### What is the file format?
All files are using the Unix format with `LF` line endings.
All files are using the Unix format with `LF` line endings. Please do not use `CRLF`.
Please do not use `CRLF`.
### Do you support multiple domains?
DMS supports multiple domains out of the box, so you can do this:
``` BASH
./setup.sh email add user1@example.com
./setup.sh email add user1@example.de
./setup.sh email add user1@server.example.org
```
### What about backups?
@ -81,52 +126,42 @@ docker run --rm -it \
find "${PWD}/docker-data/dms-backups/" -type f -mtime +30 -delete
```
### What about `docker-data/dms/mail-state` folder? (_`/var/mail-state` internally_)
### What about the `./docker-data/dms/mail-state` folder?
When you run `docker-mailserver` with the ENV var `ONE_DIR=1` (_default since v10.2_), this folder will store the data from internal services so that you can more easily persist state to disk (via `volumes`).
When you run DMS with the ENV variable `ONE_DIR=1` (default), this folder will:
This has the advantage of fail2ban blocks, ClamAV anti-virus updates and the like being kept across restarts for example.
- Provide support to persist Fail2Ban blocks, ClamAV signature updates, and the like when the container is restarted or recreated.
- To persist that container state properly this folder should be **volume mounted to `/var/mail-state/` internally**.
Service data is [relocated to the `mail-state` folder][mail-state-folders] for services: Postfix, Dovecot, Fail2Ban, Amavis, PostGrey, ClamAV, SpamAssassin.
Service data is [relocated to the `mail-state` folder][mail-state-folders] for the following services: Postfix, Dovecot, Fail2Ban, Amavis, PostGrey, ClamAV, SpamAssassin.
### I Want to Know More About the Ports
See [this part of the documentation](../config/security/understanding-the-ports/) for further details and best practice advice, **especially regarding security concerns**.
### How can I configure my email client?
Login is full email address (`<user>@<domain>`).
```properties
# imap
# IMAP
username: <user1@example.com>
password: <mypassword>
server: <mail.example.com>
imap port: 143 or 993 with ssl (recommended)
imap port: 143 or 993 with STARTTLS/SSL (recommended)
imap path prefix: INBOX
# smtp
smtp port: 25 or 587 with ssl (recommended)
# SMTP
smtp port: 25 or 587/465 with STARTTLS/SSL (recommended)
username: <user1@example.com>
password: <mypassword>
```
Please use `STARTTLS`.
DMS is properly configured for port 587, if possible, we recommend using port 465 for SMTP though. See [this section to learn more about ports](#i-want-to-know-more-about-the-ports).
### How can I manage my custom SpamAssassin rules?
### Can I use a naked/bare domain (i.e. no hostname)?
Antispam rules are managed in `docker-data/dms/config/spamassassin-rules.cf`.
### What are acceptable `SA_SPAM_SUBJECT` values?
For no subject set `SA_SPAM_SUBJECT=undef`.
For a trailing white-space subject one can define the whole variable with quotes in `docker-compose.yml`:
```yaml
environment:
- "SA_SPAM_SUBJECT=[SPAM] "
```
### Can I use naked/bare domains (no host name)?
Yes, but not without some configuration changes. Normally it is assumed that `docker-mailserver` runs on a host with a name, so the fully qualified host name might be `mail.example.com` with the domain `example.com`. The MX records point to `mail.example.com`.
Yes, but not without some configuration changes. Normally it is assumed that DMS runs on a host with a name, so the fully qualified host name might be `mail.example.com` with the domain `example.com`. The MX records point to `mail.example.com`.
To use a bare domain (_where the host name is `example.com` and the domain is also `example.com`_), change `mydestination`:
@ -143,13 +178,184 @@ 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.
### Why are SpamAssassin `x-headers` not inserted into my `subdomain.example.com` subdomain emails?
### How can I configure a catch-all?
Considering you want to redirect all incoming e-mails for the domain `example.com` to `user1@example.com`, add the following line to `docker-data/dms/config/postfix-virtual.cf`:
```cf
@example.com user1@example.com
```
### How can I delete all the emails for a specific user?
First of all, create a special alias named `devnull` by editing `docker-data/dms/config/postfix-aliases.cf`:
```cf
devnull: /dev/null
```
Considering you want to delete all the e-mails received for `baduser@example.com`, add the following line to `docker-data/dms/config/postfix-virtual.cf`:
```cf
baduser@example.com devnull
```
!!! important
If you use a catch-all rule for the main/sub domain, you need another entry in `docker-data/dms/config/postfix-virtual.cf`:
```cf
@mail.example.com hello@example.com
baduser@example.com devnull
devnull@mail.example.com devnull
```
### What kind of SSL certificates can I use?
Both RSA and ECDSA certs are supported. You can provide your own cert files manually, or mount a `letsencrypt` generated directory (_with alternative support for Traefik's `acme.json`_). Check out the [`SSL_TYPE` documentation](../config/environment/#ssl_type) for more details.
### I just moved from my old mail server to DMS, but "it doesn't work"?
If this migration implies a DNS modification, be sure to wait for DNS propagation before opening an issue.
Few examples of symptoms can be found [here][github-issue-95] or [here][github-issue-97].
This could be related to a modification of your `MX` record, or the IP mapped to `mail.example.com`. Additionally, [validate your DNS configuration](https://intodns.com/).
If everything is OK regarding DNS, please provide [formatted logs](https://guides.github.com/features/mastering-markdown/) and config files. This will allow us to help you.
If we're blind, we won't be able to do anything.
### Can DMS run in a Rancher environment?
Yes, by adding the environment variable `PERMIT_DOCKER: network`.
!!! 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].
### How can I authenticate users with `SMTP_ONLY=1`?
See [#1247][github-issue-1247] for an example.
!!! todo
Write a How-to / Use-Case / Tutorial about authentication with `SMTP_ONLY`.
### Common Errors
```log
warning: connect to Milter service inet:localhost:8893: Connection refused
# DMARC not running
# => /etc/init.d/opendmarc restart
warning: connect to Milter service inet:localhost:8891: Connection refused
# DKIM not running
# => /etc/init.d/opendkim restart
mail amavis[1459]: (01459-01) (!)connect to /var/run/clamav/clamd.ctl failed, attempt #1: Can't connect to a UNIX socket /var/run/clamav/clamd.ctl: No such file or directory
mail amavis[1459]: (01459-01) (!)ClamAV-clamd: All attempts (1) failed connecting to /var/run/clamav/clamd.ctl, retrying (2)
mail amavis[1459]: (01459-01) (!)ClamAV-clamscan av-scanner FAILED: /usr/bin/clamscan KILLED, signal 9 (0009) at (eval 100) line 905.
mail amavis[1459]: (01459-01) (!!)AV: ALL VIRUS SCANNERS FAILED
# Clamav is not running (not started or because you don't have enough memory)
# => check requirements and/or start Clamav
```
### How to use DMS behind a proxy
[Using `user-patches.sh`][docs-userpatches], update the container file `/etc/postfix/main.cf` to include:
```cf
proxy_interfaces = X.X.X.X (your public IP)
```
### How to adjust settings with the `user-patches.sh` script
Suppose you want to change a number of settings that are not listed as variables or add things to the server that are not included?
`docker-mailserver` has a built-in way to do post-install processes. If you place a script called **`user-patches.sh`** in the config directory it will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started.
It is common to use a local directory for config added to `docker-mailsever` via a volume mount in your `docker-compose.yml` (eg: `./docker-data/dms/config/:/tmp/docker-mailserver/`).
Add or create the script file to your config directory:
```sh
cd ./docker-data/dms/config
touch user-patches.sh
chmod +x user-patches.sh
```
Then fill `user-patches.sh` with suitable code.
If you want to test it you can move into the running container, run it and see if it does what you want. For instance:
```sh
# start shell in container
./setup.sh debug login
# check the file
cat /tmp/docker-mailserver/user-patches.sh
# run the script
/tmp/docker-mailserver/user-patches.sh
# exit the container shell back to the host shell
exit
```
You can do a lot of things with such a script. You can find an example `user-patches.sh` script here: [example `user-patches.sh` script][hanscees-userpatches].
We also have a [very similar docs page][docs-userpatches] specifically about this feature!
!!! attention "Special use-case - patching the `supervisord` configuration"
It seems worth noting, that the `user-patches.sh` gets executed through `supervisord`. If you need to patch some supervisord config (e.g. `/etc/supervisor/conf.d/saslauth.conf`), the patching happens too late.
An easy workaround is to make the `user-patches.sh` reload the supervisord config after patching it:
```bash
#!/bin/bash
sed -i 's/rimap -r/rimap/' /etc/supervisor/conf.d/saslauth.conf
supervisorctl update
```
### How to ban custom IP addresses with Fail2ban
Use the following command:
```bash
./setup.sh fail2ban ban <IP>
```
The default bantime is 180 days. This value can be [customized][fail2ban-customize].
### What to do in case of SPF/Forwarding problems
If you got any problems with SPF and/or forwarding mails, give [SRS](https://github.com/roehling/postsrsd/blob/master/README.rst) a try. You enable SRS by setting `ENABLE_SRS=1`. See the variable description for further information.
### SpamAssasin
#### How can I manage my custom SpamAssassin rules?
Antispam rules are managed in `docker-data/dms/config/spamassassin-rules.cf`.
#### What are acceptable `SA_SPAM_SUBJECT` values?
For no subject set `SA_SPAM_SUBJECT=undef`.
For a trailing white-space subject one can define the whole variable with quotes in `docker-compose.yml`:
```yaml
environment:
- "SA_SPAM_SUBJECT=[SPAM] "
```
#### Why are SpamAssassin `x-headers` not inserted into my `subdomain.example.com` subdomain emails?
In the default setup, amavis only applies SpamAssassin x-headers into domains matching the template listed in the config file (`05-domain_id` in the amavis defaults).
The default setup `@local_domains_acl = ( ".$mydomain" );` does not match subdomains. To match subdomains, you can override the `@local_domains_acl` directive in the amavis user config file `50-user` with `@local_domains_maps = (".");` to match any sort of domain template.
### How can I make SpamAssassin better recognize spam?
#### How can I make SpamAssassin better recognize spam?
Put received spams in `.Junk/` imap folder using `SPAMASSASSIN_SPAM_TO_INBOX=1` and `MOVE_SPAM_TO_JUNK=1` and add a _user_ cron like the following:
@ -235,38 +441,7 @@ The following configuration works nicely:
With the default settings, SpamAssassin will require 200 mails trained for spam (for example with the method explained above) and 200 mails trained for ham (using the same command as above but using `--ham` and providing it with some ham mails). Until you provided these 200+200 mails, SpamAssassin will not take the learned mails into account. For further reference, see the [SpamAssassin Wiki](https://wiki.apache.org/spamassassin/BayesNotWorking).
### How can I configure a catch-all?
Considering you want to redirect all incoming e-mails for the domain `example.com` to `user1@example.com`, add the following line to `docker-data/dms/config/postfix-virtual.cf`:
```cf
@example.com user1@example.com
```
### How can I delete all the emails for a specific user?
First of all, create a special alias named `devnull` by editing `docker-data/dms/config/postfix-aliases.cf`:
```cf
devnull: /dev/null
```
Considering you want to delete all the e-mails received for `baduser@example.com`, add the following line to `docker-data/dms/config/postfix-virtual.cf`:
```cf
baduser@example.com devnull
```
!!! important
If you use a catch-all rule for the main/sub domain, you need another entry in `docker-data/dms/config/postfix-virtual.cf`:
```cf
@mail.example.com hello@example.com
baduser@example.com devnull
devnull@mail.example.com devnull
```
### How do I have more control about what SPAMASSASIN is filtering?
#### How do I have more control about what SpamAssassin is filtering?
By default, SPAM and INFECTED emails are put to a quarantine which is not very straight forward to access. Several config settings are affecting this behavior:
@ -312,140 +487,6 @@ $bad_header_quarantine_to = "amavis\@example.com";
$spam_quarantine_to = "amavis\@example.com";
```
### What kind of SSL certificates can I use?
You can use the same certificates you would use with another mail-server.
The only difference is that we provide a `self-signed` certificate tool and a `letsencrypt` certificate loader.
### I just moved from my old Mail-Server, but "it doesn't work"?
If this migration implies a DNS modification, be sure to wait for DNS propagation before opening an issue.
Few examples of symptoms can be found [here][github-issue-95] or [here][github-issue-97].
This could be related to a modification of your `MX` record, or the IP mapped to `mail.example.com`. Additionally, [validate your DNS configuration](https://intodns.com/).
If everything is OK regarding DNS, please provide [formatted logs](https://guides.github.com/features/mastering-markdown/) and config files. This will allow us to help you.
If we're blind, we won't be able to do anything.
### What system requirements are required to run `docker-mailserver` effectively?
1 core and 1GB of RAM + swap partition is recommended to run `docker-mailserver` with ClamAV.
Otherwise, it could work with 512M of RAM.
!!! warning
ClamAV can consume a lot of memory, as it reads the entire signature database into RAM.
Current figure is about 850M and growing. If you get errors about ClamAV or amavis failing to allocate memory you need more RAM or more swap and of course docker must be allowed to use swap (not always the case). If you can't use swap at all you may need 3G RAM.
### Can `docker-mailserver` run in a Rancher Environment?
Yes, by adding the environment variable `PERMIT_DOCKER: network`.
!!! 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].
### How can I Authenticate Users with `SMTP_ONLY`?
See [#1247][github-issue-1247] for an example.
!!! todo
Write a How-to / Use-Case / Tutorial about authentication with `SMTP_ONLY`.
### Common Errors
```log
warning: connect to Milter service inet:localhost:8893: Connection refused
# DMARC not running
# => /etc/init.d/opendmarc restart
warning: connect to Milter service inet:localhost:8891: Connection refused
# DKIM not running
# => /etc/init.d/opendkim restart
mail amavis[1459]: (01459-01) (!)connect to /var/run/clamav/clamd.ctl failed, attempt #1: Can't connect to a UNIX socket /var/run/clamav/clamd.ctl: No such file or directory
mail amavis[1459]: (01459-01) (!)ClamAV-clamd: All attempts (1) failed connecting to /var/run/clamav/clamd.ctl, retrying (2)
mail amavis[1459]: (01459-01) (!)ClamAV-clamscan av-scanner FAILED: /usr/bin/clamscan KILLED, signal 9 (0009) at (eval 100) line 905.
mail amavis[1459]: (01459-01) (!!)AV: ALL VIRUS SCANNERS FAILED
# Clamav is not running (not started or because you don't have enough memory)
# => check requirements and/or start Clamav
```
### How to use when behind a Proxy
[Using `user-patches.sh`][docs-userpatches], update the container file `/etc/postfix/main.cf` to include:
```cf
proxy_interfaces = X.X.X.X (your public IP)
```
### What About Updates
You can use your own scripts, or every now and then `pull && stop && rm && start` the images but there are tools already available for this.
There is a section in the [Update and Cleanup][docs-maintenance] documentation page that explains how to do it the docker way.
### How to adjust settings with the `user-patches.sh` script
Suppose you want to change a number of settings that are not listed as variables or add things to the server that are not included?
`docker-mailserver` has a built-in way to do post-install processes. If you place a script called **`user-patches.sh`** in the config directory it will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started.
It is common to use a local directory for config added to `docker-mailsever` via a volume mount in your `docker-compose.yml` (eg: `./docker-data/dms/config/:/tmp/docker-mailserver/`).
Add or create the script file to your config directory:
```sh
cd ./docker-data/dms/config
touch user-patches.sh
chmod +x user-patches.sh
```
Then fill `user-patches.sh` with suitable code.
If you want to test it you can move into the running container, run it and see if it does what you want. For instance:
```sh
# start shell in container
./setup.sh debug login
# check the file
cat /tmp/docker-mailserver/user-patches.sh
# run the script
/tmp/docker-mailserver/user-patches.sh
# exit the container shell back to the host shell
exit
```
You can do a lot of things with such a script. You can find an example `user-patches.sh` script here: [example `user-patches.sh` script][hanscees-userpatches].
We also have a [very similar docs page][docs-userpatches] specifically about this feature!
#### Special use-case - Patching the `supervisord` config
It seems worth noting, that the `user-patches.sh` gets executed through `supervisord`. If you need to patch some supervisord config (e.g. `/etc/supervisor/conf.d/saslauth.conf`), the patching happens too late.
An easy workaround is to make the `user-patches.sh` reload the supervisord config after patching it:
```bash
#!/bin/bash
sed -i 's/rimap -r/rimap/' /etc/supervisor/conf.d/saslauth.conf
supervisorctl update
```
### How to ban custom IP addresses with Fail2ban
Use the following command:
```bash
./setup.sh fail2ban ban <IP>
```
The default bantime is 180 days. This value can be [customized][fail2ban-customize].
[fail2ban-customize]: ./config/security/fail2ban.md
[docs-maintenance]: ./config/advanced/maintenance/update-and-cleanup.md
[docs-userpatches]: ./config/advanced/override-defaults/user-patches.md

73
docs/content/index.md
View File

@ -2,36 +2,65 @@
title: Home
---
# Welcome to the Extended Documentation for `docker-mailserver`!
# Welcome to the Documentation for `docker-mailserver`!
Please first have a look at the [`README.md`][github-file-readme] to setup and configure this server.
!!! info "This Documentation is Versioned"
This documentation provides you with advanced configuration, detailed examples, and hints.
**Make sure** to select the correct version of this documentation! It should match the version of the image you are using. The default version corresponds to the `:edge` image tag - [the most recent build, not the most recent stable release][docs-tagging].
## Getting Started
This documentation provides you not only with the basic setup and configuration of DMS but also with advanced configuration, elaborate usage scenarios, detailed examples, hints and more.
1. The script [`setup.sh`][github-file-setupsh] is supplied with this project. It supports you in **configuring and administrating** your server. Information on how to get it and how to use it is available [on a dedicated page][docs-setupsh].
2. Be aware that advanced tasks may still require tweaking environment variables, reading through documentation and sometimes inspecting your running container for debugging purposes. After all, a mail-server is a complex arrangement of various programs.
3. A list of all configuration options is documented on [the ENV page][docs-environment]. The [`README.md`][github-file-readme] is a good starting point to understand what this image is capable of.
4. A list of all optional and automatically created configuration files and directories is available [on the dedicated page][docs-optionalconfig].
5. If you want to know more about our test suite, view our [testing docs][docs-tests].
[docs-tagging]: ./usage/#available-images-tags-tagging-convention
!!! tip
See the [FAQ][docs-faq] for some more tips!
## About
`docker-mailserver`, or DMS for short, is a production-ready fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.). It employs only configuration files, no SQL database. The image is focused around the slogan "Keep it simple and versioned".
## Contents
### Getting Started
If you're completely new to mail servers or you want to read up on them, check out our [_Introduction_ page][docs-introduction]. If you're new to DMS as a mail server appliance, make sure to read the [_Usage_ chapter][docs-usage] first. If you want to look at examples for Docker Compose, we have an [_Examples_ page][docs-examples].
There is also a script - [`setup.sh`][github-file-setupsh] - supplied with this project. It supports you in configuring and administrating your server. Information on how to get it and how to use it is available [on a dedicated page][docs-setupsh].
[docs-introduction]: ./introduction/
[docs-usage]: ./usage/
[docs-examples]: ./examples/tutorials/basic-installation/
[github-file-setupsh]: https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh
[docs-setupsh]: ./config/setup.sh/
### Configuration
We have a [dedicated configuration page][docs-environment]. It contains most of the configuration and explanation you need to setup _your_ mail server properly. Be aware that advanced tasks may still require reading through all parts of this documentation; it may also involve inspecting your running container for debugging purposes. After all, a mail-server is a complex arrangement of various programs.
!!! important
If you'd like to change, patch or alter files or behavior of `docker-mailserver`, you can use a script. Just place a script called `user-patches.sh` in your `./docker-data/dms/config/` folder volume and it will be run on container startup. See the ['Modifications via Script' page][docs-userpatches]for additional documentation and an example.
## Contributing
If you'd like to change, patch or alter files or behavior of `docker-mailserver`, you can use a script. Just place a script called `user-patches.sh` in your `./docker-data/dms/config/` folder volume (which is mounted to `/tmp/docker-mailserver/` inside the container) and it will be run on container startup. See the ['Modifications via Script' page][docs-userpatches] for additional documentation and an example.
You might also want to check out:
1. A list of [all configuration options via ENV][docs-environment]
2. A list of [all optional and automatically created configuration files and directories][docs-optionalconfig]
!!! tip
Definitely check out the [FAQ][docs-faq] for more information and tips! Please do not open an issue before you have checked our documentation for answers, including the [FAQ][docs-faq]!
[docs-environment]: ./config/environment/
[docs-userpatches]: ./faq/#how-to-adjust-settings-with-the-user-patchessh-script
[docs-setupsh]: ./config/setup.sh/
[docs-optionalconfig]: ./config/advanced/optional-config/
[docs-faq]: ./faq/
### Tests
DMS employs a variety of tests. If you want to know more about our test suite, view our [testing docs][docs-tests].
[docs-tests]: ./contributing/tests/
### Contributing
We are always happy to welcome new contributors. For guidelines and entrypoints please have a look at the [Contributing section][docs-contributing].
[docs-tests]: ./contributing/tests.md
[docs-contributing]: ./contributing/issues-and-pull-requests.md
[docs-faq]: ./faq.md
[docs-optionalconfig]: ./config/advanced/optional-config.md
[docs-setupsh]: ./config/setup.sh.md
[docs-userpatches]: ./config/advanced/override-defaults/user-patches.md
[docs-environment]: ./config/environment.md
[github-file-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md
[github-file-setupsh]: https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh
[docs-contributing]: ./contributing/issues-and-pull-requests/

133
docs/content/usage.md Normal file
View File

@ -0,0 +1,133 @@
---
title: Usage
---
This pages explains how to get started with DMS, basically explaining how you can use it. The procedure uses Docker Compose as a reference. In our examples, [`/docker-data/dms/config/`](../faq/#what-about-the-docker-datadmsmail-state-folder) on the host is mounted to `/tmp/docker-mailserver/` inside the container.
## Available Images / Tags - Tagging Convention
[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:
1. DockerHub ([`docker.io/mailserver/docker-mailserver`](https://hub.docker.com/r/mailserver/docker-mailserver))
2. GitHub Container Registry ([`ghcr.io/docker-mailserver/docker-mailserver`](https://github.com/docker-mailserver/docker-mailserver/pkgs/container/docker-mailserver))
All workflows are using the tagging convention listed below. It is subsequently applied to all images.
| Event | Image Tags |
|-------------------------|-------------------------------|
| `push` on `master` | `edge` |
| `push` a tag (`v1.2.3`) | `1.2.3`, `1.2`, `1`, `latest` |
## Get the Tools
!!! note "`setup.sh` Not Required Anymore"
Since DMS `v10.2.0`, [`setup.sh` functionality](../faq/#how-to-adjust-settings-with-the-user-patchessh-script) is included within the container image. The external convenience script is no longer required if you prefer using `docker exec <CONTAINER NAME> setup <COMMAND>` instead.
Issue the following commands to acquire the necessary files:
``` BASH
DMS_GITHUB_URL='https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master'
wget "${DMS_GITHUB_URL}/docker-compose.yml"
wget "${DMS_GITHUB_URL}/mailserver.env"
# Optional
wget "${DMS_GITHUB_URL}/setup.sh"
chmod a+x ./setup.sh
```
## Create a docker-compose Environment
1. [Install the latest Docker Compose](https://docs.docker.com/compose/install/)
2. Edit `docker-compose.yml` to your liking
- substitute `mail.example.com` according to your FQDN
- if you want to use SELinux for the `./docker-data/dms/config/:/tmp/docker-mailserver/` mount, append `-z` or `-Z`
3. Configure the mailserver container to your liking by editing `mailserver.env` ([**Documentation**](https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/)), but keep in mind this `.env` file:
- [_only_ basic `VAR=VAL`](https://docs.docker.com/compose/env-file/) is supported (**do not** quote your values)
- variable substitution is **not** supported (e.g. :no_entry_sign: `OVERRIDE_HOSTNAME=$HOSTNAME.$DOMAINNAME` :no_entry_sign:)
!!! info "Podman Support"
If you're using podman, make sure to read the related [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/advanced/podman/)
## Get up and running
### First Things First
!!! danger "Using the Correct Commands For Stopping and Starting DMS"
**Use `docker compose up / down`, not `docker compose start / stop`**. Otherwise, the container is not properly destroyed and you may experience problems during startup because of inconsistent state.
You are able to get a full overview of how the configuration works by either running:
1. `./setup.sh help` which includes the options of `setup.sh`.
2. `docker run --rm docker.io/mailserver/docker-mailserver:latest setup help` which provides you with all the information on configuration provided "inside" the container itself.
??? info "Usage of `setup.sh` when no DMS Container Is Running"
If no DMS container is running, any `./setup.sh` command will check online for the `:latest` image tag (the current _stable_ release), performing a `docker pull ...` if necessary followed by running the command in a temporary container:
```console
$ ./setup.sh help
Image 'docker.io/mailserver/docker-mailserver:latest' not found. Pulling ...
SETUP(1)
NAME
setup - 'docker-mailserver' Administration & Configuration script
...
$ docker run --rm docker.io/mailserver/docker-mailserver:latest setup help
SETUP(1)
NAME
setup - 'docker-mailserver' Administration & Configuration script
...
```
### Starting for the first time
On first start, you will need to add at least one email account (unless you're using LDAP). You have two minutes to do so, otherwise DMS will shutdown and restart. You can add accounts with the following two methods:
1. Use `setup.sh`: `./setup.sh email add <user@domain>`
2. Run the command directly in the container: `docker exec -ti <CONTAINER NAME> setup email add <user@domain>`
You can then proceed by creating the postmaster alias and by creating DKIM keys.
``` BASH
docker-compose up -d mailserver
# you may add some more users
# for SELinux, use -Z
./setup.sh [-Z] email add <user@domain> [<password>]
# and configure aliases, DKIM and more
./setup.sh [-Z] alias add postmaster@<domain> <user@domain>
```
## Further Miscellaneous Steps
### DNS - DKIM
You can (and you should) generate DKIM keys by running
``` BASH
./setup.sh [-Z] config dkim
```
If you want to see detailed usage information, run
``` BASH
./setup.sh config dkim help
```
In case you're using LDAP, the setup looks a bit different as you do not add user accounts directly. Postfix doesn't know your domain(s) and you need to provide it when configuring DKIM:
``` BASH
./setup.sh config dkim domain '<domain.tld>[,<domain2.tld>]'
```
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](./config/best-practices/dkim.md) for more details.
### Custom User Changes & Patches
If you'd like to change, patch or alter files or behavior of `docker-mailserver`, you can use a script. See [this part of our documentation](./faq.md/#how-to-adjust-settings-with-the-user-patchessh-script) for a detailed explanation.

3
docs/mkdocs.yml
View File

@ -111,9 +111,10 @@ markdown_extensions:
nav:
- 'Home': index.md
- 'Introduction': introduction.md
- 'Usage': usage.md
- 'Configuration':
- 'Your Best Friend setup.sh': config/setup.sh.md
- 'Environment Variables': config/environment.md
- 'Your Best Friend setup.sh': config/setup.sh.md
- 'User Management':
- 'Accounts': config/user-management/accounts.md
- 'Aliases': config/user-management/aliases.md