295 lines
14 KiB
Markdown
295 lines
14 KiB
Markdown
---
|
|
tags:
|
|
- Documentation
|
|
- Bookstack
|
|
- Notes
|
|
---
|
|
# Mailcow
|
|
|
|
# Installation
|
|
|
|
# Installation of mailcow[¶](https://docs.mailcow.email/getstarted/install/#installation-of-mailcow "Permanent link")
|
|
|
|
## Prerequisites[¶](https://docs.mailcow.email/getstarted/install/#prerequisites "Permanent link")
|
|
|
|
### System Packages[¶](https://docs.mailcow.email/getstarted/install/#system-packages "Permanent link")
|
|
|
|
The following Linux packages are required for using mailcow and may need to be installed depending on your distribution:
|
|
|
|
- git
|
|
- openssl
|
|
- curl
|
|
- awk
|
|
- sha1sum
|
|
- grep
|
|
- cut
|
|
- jq (**new as of [2025-09](https://mailcow.email/posts/2025/release-2025-09/#2025-09-release-10th-september-2025)**)
|
|
|
|
### Docker and Docker Compose[¶](https://docs.mailcow.email/getstarted/install/#docker-and-docker-compose "Permanent link")
|
|
|
|
For the installation, you will need:
|
|
|
|
- **Docker**: Version `>= 24.0.0`
|
|
- **Docker Compose**: Version `>= 2.0`
|
|
|
|
Installation guides can be found here:
|
|
|
|
- [Install Docker](https://docs.docker.com/install/)
|
|
- [Install Docker Compose](https://docs.docker.com/compose/install/)
|
|
|
|
### Quick Installation[¶](https://docs.mailcow.email/getstarted/install/#quick-installation "Permanent link")
|
|
|
|
#### System Packages[¶](https://docs.mailcow.email/getstarted/install/#system-packages_1 "Permanent link")
|
|
|
|
##### Debian/Ubuntu:[¶](https://docs.mailcow.email/getstarted/install/#debianubuntu "Permanent link")
|
|
|
|
```
|
|
apt update
|
|
apt install -y git openssl curl gawk coreutils grep jq
|
|
|
|
```
|
|
|
|
#### Docker[¶](https://docs.mailcow.email/getstarted/install/#docker "Permanent link")
|
|
|
|
Important
|
|
|
|
Use the **latest available Docker Engine** and not the version from your Linux distribution's package sources.
|
|
|
|
##### Debian/Ubuntu:[¶](https://docs.mailcow.email/getstarted/install/#debianubuntu_1 "Permanent link")
|
|
|
|
```
|
|
curl -sSL https://get.docker.com/ | CHANNEL=stable sh
|
|
systemctl enable --now docker
|
|
|
|
```
|
|
|
|
#### Docker Compose[¶](https://docs.mailcow.email/getstarted/install/#docker-compose "Permanent link")
|
|
|
|
Warning
|
|
|
|
**mailcow requires Docker Compose version `>= 2.0`.**
|
|
|
|
##### Installation via Package Manager (Plugin)[¶](https://docs.mailcow.email/getstarted/install/#installation-via-package-manager-plugin "Permanent link")
|
|
|
|
Note
|
|
|
|
This method requires that the Docker repository has been added (see [Docker](https://docs.mailcow.email/getstarted/install/#docker)).
|
|
|
|
###### Debian/Ubuntu:[¶](https://docs.mailcow.email/getstarted/install/#debianubuntu_2 "Permanent link")
|
|
|
|
```
|
|
apt update
|
|
apt install docker-compose-plugin
|
|
|
|
```
|
|
|
|
## Installing mailcow[¶](https://docs.mailcow.email/getstarted/install/#installing-mailcow "Permanent link")
|
|
|
|
1. Clone the repository:
|
|
|
|
```
|
|
su
|
|
umask 0022
|
|
cd /opt
|
|
git clone https://github.com/mailcow/mailcow-dockerized
|
|
cd mailcow-dockerized
|
|
|
|
```
|
|
2. Generate the configuration file:
|
|
|
|
```
|
|
./generate_config.sh
|
|
|
|
```
|
|
3. Adjust the configuration if necessary:
|
|
|
|
```
|
|
nano mailcow.conf
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## Starting mailcow[¶](https://docs.mailcow.email/getstarted/install/#starting-mailcow "Permanent link")
|
|
|
|
Download the images and start the containers:
|
|
|
|
<div class="tabbed-set tabbed-alternate" id="bkmrk-docker-compose-%28plug"><div class="tabbed-labels tabbed-labels--linked">[Docker Compose (Plugin)](https://docs.mailcow.email/getstarted/install/#__tabbed_1_1)[Docker Compose (Standalone)](https://docs.mailcow.email/getstarted/install/#__tabbed_1_2)</div><div class="tabbed-content"><div class="tabbed-block"><div class="highlight"><nav class="md-code__nav"></nav></div></div></div></div>```
|
|
docker compose pull
|
|
docker compose up -d
|
|
|
|
```
|
|
|
|
<div class="tabbed-set tabbed-alternate" id="bkmrk--3"><div class="tabbed-content"><div class="tabbed-block"><div class="highlight"></div></div></div><div class="tabbed-control tabbed-control--prev">
|
|
</div><div class="tabbed-control tabbed-control--next">
|
|
</div></div>Done!
|
|
|
|
You can now access **`https://${MAILCOW_HOSTNAME}/admin`** using the default credentials `admin` and the password `moohoo`.
|
|
|
|
---
|
|
|
|
## Troubleshooting[¶](https://docs.mailcow.email/getstarted/install/#troubleshooting "Permanent link")
|
|
|
|
### MTU not equal to 1500 (e.g., OpenStack)[¶](https://docs.mailcow.email/getstarted/install/#mtu-not-equal-to-1500-eg-openstack "Permanent link")
|
|
|
|
Adjust the network settings in `docker-compose.yml`:
|
|
|
|
```
|
|
networks:
|
|
mailcow-network:
|
|
driver_opts:
|
|
com.docker.network.driver.mtu: 1450
|
|
|
|
```
|
|
|
|
### No IPv6 on the Host System[¶](https://docs.mailcow.email/getstarted/install/#no-ipv6-on-the-host-system "Permanent link")
|
|
|
|
Disable IPv6 for the mailcow network if your host system does not support IPv6. More information can be found [here](https://docs.mailcow.email/post_installation/firststeps-disable_ipv6/).
|
|
|
|
---
|
|
|
|
## Important Notes[¶](https://docs.mailcow.email/getstarted/install/#important-notes "Permanent link")
|
|
|
|
- **Data Persistence**: Your data is stored in Docker volumes and remains intact even if you recreate or delete containers.
|
|
- **Reverse Proxy**: If you are not using a reverse proxy, you should [redirect HTTP to HTTPS](https://docs.mailcow.email/manual-guides/u_e-80_to_443/).
|
|
|
|
# DNS Entries
|
|
|
|
Below you can find a list of **recommended DNS records**. While some are mandatory for a mail server (A, MX), others are recommended to build a good reputation score (TXT/SPF) or used for auto-configuration of mail clients (SRV).
|
|
|
|
## References[¶](https://docs.mailcow.email/getstarted/prerequisite-dns/#references "Permanent link")
|
|
|
|
- A good article covering all relevant topics: ["3 DNS Records Every Email Marketer Must Know"](https://www.rackaid.com/blog/email-dns-records)
|
|
- Another great one, but Zimbra as an example platform: ["Best Practices on Email Protection: SPF, DKIM and DMARC"](https://wiki.zimbra.com/wiki/Best_Practices_on_Email_Protection:_SPF,_DKIM_and_DMARC)
|
|
- An in-depth discussion of SPF, DKIM and DMARC: ["How to eliminate spam and protect your name with DMARC"](https://www.skelleton.net/2015/03/21/how-to-eliminate-spam-and-protect-your-name-with-dmarc/)
|
|
- A thorough guide on understanding DMARC: ["Demystifying DMARC: A guide to preventing email spoofing"](https://seanthegeek.net/459/demystifying-dmarc/)
|
|
|
|
## Reverse DNS of your IP address[¶](https://docs.mailcow.email/getstarted/prerequisite-dns/#reverse-dns-of-your-ip-address "Permanent link")
|
|
|
|
Make sure that the PTR record of your IP address matches the FQDN of your mailcow host: `${MAILCOW_HOSTNAME}` <sup id="bkmrk-1">[1](https://docs.mailcow.email/getstarted/prerequisite-dns/#fn:1)</sup>. This record is usually set at the provider you leased the IP address (server) from. Please make sure that you create the record for IPv4 and IPv6 address (if you are using IPv6)!
|
|
|
|
## The minimal DNS configuration[¶](https://docs.mailcow.email/getstarted/prerequisite-dns/#the-minimal-dns-configuration "Permanent link")
|
|
|
|
This example shows you a set of records for one domain managed by mailcow. Each domain that is added to mailcow needs at least this set of records to function correctly.
|
|
|
|
```
|
|
# Name Type Value
|
|
mail IN A 1.2.3.4
|
|
autodiscover IN CNAME mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
autoconfig IN CNAME mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
@ IN MX 10 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
|
|
```
|
|
|
|
**Note:** The `mail` DNS record which binds the subdomain to the given ip address must only be set for the domain on which mailcow is running and that is used to access the web interface. For every other mailcow managed domain, the `MX` record will route the traffic.
|
|
|
|
## DKIM, SPF and DMARC[¶](https://docs.mailcow.email/getstarted/prerequisite-dns/#dkim-spf-and-dmarc "Permanent link")
|
|
|
|
In the example DNS zone file snippet below, a simple **SPF** TXT record is used to only allow THIS server (the MX) to send mail for your domain. Every other server is disallowed but able to ("`~all`"). Please refer to [SPF Project](http://www.open-spf.org/) for further reading.
|
|
|
|
```
|
|
# Name Type Value
|
|
@ IN TXT "v=spf1 mx a -all"
|
|
|
|
```
|
|
|
|
It is highly recommended to create a **DKIM** TXT record in your mailcow UI and set the corresponding TXT record in your DNS records. Please refer to [OpenDKIM](http://www.opendkim.org/) for further reading.
|
|
|
|
```
|
|
# Name Type Value
|
|
dkim._domainkey IN TXT "v=DKIM1; k=rsa; t=s; s=email; p=..."
|
|
|
|
```
|
|
|
|
The last step in protecting yourself and others is the implementation of a **DMARC** TXT record, for example by using the [DMARC Assistant](http://www.kitterman.com/dmarc/assistant.html) ([check](https://dmarcian.com/dmarc-inspector/google.com)).
|
|
|
|
```
|
|
# Name Type Value
|
|
_dmarc IN TXT "v=DMARC1; p=reject; rua=mailto:mailauth-reports@example.org"
|
|
|
|
```
|
|
|
|
## The advanced DNS configuration[¶](https://docs.mailcow.email/getstarted/prerequisite-dns/#the-advanced-dns-configuration "Permanent link")
|
|
|
|
**SRV** records specify the server(s) for a specific protocol on your domain. If you want to explicitly announce a service as not provided, give "." as the target address (instead of "mail.example.org."). Please refer to [RFC 2782](https://tools.ietf.org/html/rfc2782).
|
|
|
|
```
|
|
# Name Type Priority Weight Port Value
|
|
_autodiscover._tcp IN SRV 0 1 443 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
_caldavs._tcp IN SRV 0 1 443 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
_caldavs._tcp IN TXT "path=/SOGo/dav/"
|
|
_carddavs._tcp IN SRV 0 1 443 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
_carddavs._tcp IN TXT "path=/SOGo/dav/"
|
|
_imap._tcp IN SRV 0 1 143 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
_imaps._tcp IN SRV 0 1 993 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
_pop3._tcp IN SRV 0 1 110 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
_pop3s._tcp IN SRV 0 1 995 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
_sieve._tcp IN SRV 0 1 4190 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
_smtps._tcp IN SRV 0 1 465 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
_submission._tcp IN SRV 0 1 587 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
_submissions._tcp IN SRV 0 1 465 mail.example.org. (your ${MAILCOW_HOSTNAME})
|
|
|
|
```
|
|
|
|
## Testing[¶](https://docs.mailcow.email/getstarted/prerequisite-dns/#testing "Permanent link")
|
|
|
|
Here are some tools you can use to verify your DNS configuration:
|
|
|
|
- [MX Toolbox](https://mxtoolbox.com/SuperTool.aspx) (DNS, SMTP, RBL)
|
|
- [port25.com](https://www.port25.com/dkim-wizard/) (DKIM, SPF)
|
|
- [Mail-tester](https://www.mail-tester.com/) (DKIM, DMARC, SPF)
|
|
- [DMARC Analyzer](https://www.dmarcanalyzer.com/spf/checker/) (DMARC, SPF)
|
|
- [MultiRBL.valli.org](http://multirbl.valli.org/) (DNSBL, RBL, FCrDNS)
|
|
|
|
## Misc[¶](https://docs.mailcow.email/getstarted/prerequisite-dns/#misc "Permanent link")
|
|
|
|
### Optional DMARC Statistics[¶](https://docs.mailcow.email/getstarted/prerequisite-dns/#optional-dmarc-statistics "Permanent link")
|
|
|
|
If you are interested in statistics, you can additionally register with some of the many below DMARC statistic services - or self-host your own.
|
|
|
|
Tip
|
|
|
|
It is worth considering that if you request DMARC statistic reports to your mailcow server and your mailcow server is not configured correctly to receive these reports, you may not get accurate and complete results. Please consider using an alternative email domain for receiving DMARC reports.
|
|
|
|
It is worth mentioning, that the following suggestions are not a comprehensive list of all services and tools available, but only a small few of the many choices.
|
|
|
|
- [Postmaster Tool](https://postmaster.google.com/v2/manage_domains)
|
|
- [parsedmarc](https://github.com/domainaware/parsedmarc) (self-hosted)
|
|
- [Fraudmarc](https://fraudmarc.com/)
|
|
- [Postmark](https://dmarc.postmarkapp.com/)
|
|
- [Dmarcian](https://dmarcian.com/)
|
|
|
|
Tip
|
|
|
|
These services may provide you with a TXT record you need to insert into your DNS records as the provider specifies. Please ensure you read the provider's documentation from the service you choose as this process may vary.
|
|
|
|
### Email test for SPF, DKIM and DMARC:[¶](https://docs.mailcow.email/getstarted/prerequisite-dns/#email-test-for-spf-dkim-and-dmarc "Permanent link")
|
|
|
|
To run a rudimentary email authentication check, send a mail to `check-auth at verifier.port25.com` and wait for a reply. You will find a report similar to the following:
|
|
|
|
```
|
|
==========================================================
|
|
Summary of Results
|
|
==========================================================
|
|
SPF check: pass
|
|
"iprev" check: pass
|
|
DKIM check: pass
|
|
DKIM check: pass
|
|
SpamAssassin check: ham
|
|
|
|
==========================================================
|
|
Details:
|
|
==========================================================
|
|
....
|
|
|
|
```
|
|
|
|
The full report will contain more technical details.
|
|
|
|
### Fully Qualified Domain Name (FQDN)[¶](https://docs.mailcow.email/getstarted/prerequisite-dns/#fully-qualified-domain-name-fqdn "Permanent link")
|
|
|
|
<div class="footnote" id="bkmrk-a%C2%A0fully-qualified-do">---
|
|
|
|
1. A **Fully Qualified Domain Name** (**FQDN**) is the complete (absolute) domain name for a specific computer or host, on the Internet. The FQDN consists of at least three parts divided by a dot: the hostname, the domain name, and the Top Level Domain (**TLD** for short). In the example of `mx.mailcow.email` the hostname would be `mx`, the domain name `mailcow` and the TLD `email`. [↩](https://docs.mailcow.email/getstarted/prerequisite-dns/#fnref:1 "Jump back to footnote 1 in the text")
|
|
|
|
</div> |