Deploying Mailcow with Docker and Traefik for a Full E-Mail Stack

Mailcow is a powerful and flexible open-source mail server suite that allows you to manage your email communications securely and efficiently. With Mailcow, you can create multiple email domains and accounts, manage users, and leverage features like spam filtering and encryption, giving you full control over your email infrastructure. This guide will show you how to set up Mailcow using Docker Compose behind an existing Traefik reverse proxy.

Changelog

1. Prerequisites

This guide assumes you have a fully functional server environment with the following components already set up:

• Traefik v3 and CrowdSec with Docker Compose: This is the foundation for our reverse proxy, security, and certificate management.
• Docker and Docker Compose: Must be installed on your server.
• Required Tools: You will need git and jq. Install them with:

  sudo apt update && sudo apt install -y git jq
  

• sudo or root access.

2. Directory Structure

First, create a dedicated directory for your Mailcow installation.

sudo mkdir -p /opt/containers/mailcow

3. Clone the Mailcow Repository

Clone the latest version of the Mailcow Dockerized project from GitHub into the directory you just created.

sudo git clone https://github.com/mailcow/mailcow-dockerized /opt/containers/mailcow

4. Generate the Configuration File

Navigate into the new directory and run the configuration generation script.

cd /opt/containers/mailcow
./generate_config.sh

You will be prompted for the following information:

• Mail server hostname (FQDN): Enter the fully qualified domain name for your mail server, for example, mail.your-domain.com.
• Timezone: Press Enter to accept the default or provide your own.
• Available Branches: Press 1 to select the master branch.

5. Configure for Traefik Integration

To make Mailcow work with our external Traefik instance, we need to create an override file and modify the main configuration.

5.1. Create docker-compose.override.yml

This file contains all our customizations, telling Mailcow to use the external proxy network and defining labels for Traefik to route traffic correctly. It also sets up a certdumper service, which is crucial for sharing Traefik’s Let’s Encrypt certificates with Mailcow’s services (Postfix and Dovecot).

Create the file:

sudo tee /opt/containers/mailcow/docker-compose.override.yml > /dev/null << 'EOF'
networks:
  proxy:
    name: proxy
    external: true

services:
  certdumper:
    image: ghcr.io/kereis/traefik-certs-dumper:latest
    restart: unless-stopped
    network_mode: none
    # Correct command to restart containers by their full name. Mailcow's project name is "mailcowdockerized".
    command: --restart-containers mailcowdockerized-postfix-mailcow-1,mailcowdockerized-dovecot-mailcow-1
    volumes:
      # Adjust this path to match YOUR Traefik stack's certificate location
      - /opt/containers/traefik-stack/traefik/certs:/traefik:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./data/assets/ssl:/output:rw
    environment:
      DOMAIN: ${MAILCOW_HOSTNAME}
      # Adjust this to match YOUR Traefik acme file name
      ACME_FILE_PATH: "/traefik/acme.json"
    healthcheck:
      test: ["CMD", "/usr/bin/healthcheck"]
      interval: 30s
      timeout: 10s
      retries: 5

  nginx-mailcow:
    # We use !reset to completely remove the default port bindings set by Mailcow.
    ports: !reset
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"

      # HTTPS Router (Secure)
      # The HTTP to HTTPS redirect is handled globally by our Traefik setup, so we only need the secure router.
      - "traefik.http.routers.nginx-mailcow-secure.entrypoints=websecure"
      - "traefik.http.routers.nginx-mailcow-secure.rule=Host(`mail.your-domain.com`) || Host(`autodiscover.your-domain.com`) || Host(`autoconfig.your-domain.com`) || Host(`mta-sts.your-domain.com`)"
      - "traefik.http.routers.nginx-mailcow-secure.tls=true"
      - "traefik.http.routers.nginx-mailcow-secure.tls.certresolver=tls_resolver"
      - "traefik.http.routers.nginx-mailcow-secure.service=nginx-mailcow"
      - "traefik.http.routers.nginx-mailcow-secure.middlewares=security-headers@file,crowdsec-bouncer@docker"

      # Service Definition: Point to Mailcow's internal Nginx port.
      # This must be 80, as we are NOT changing the internal ports in mailcow.conf
      - "traefik.http.services.nginx-mailcow.loadbalancer.server.port=80"
EOF

sudo sed -i "s/your-domain.com/your-actual-domain.com/g" docker-compose.override.yml

5.2. Adjust mailcow.conf

Next, edit the main configuration file. There are only two changes needed here.

sudo nano /opt/containers/mailcow/mailcow.conf```

<!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre -->
<!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box -->
<!-- Types: info, warning, tip, note -->


<table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1">
    <tr>
        <td bgcolor="#eeeeee" style="color: #000000; font-weight: bold;">
            ℹ️ 
            CRITICAL: DO NOT CHANGE PORTS OR BINDINGS!
        </td>
    </tr>
    <tr>
        <td bgcolor="#000000" style="color: #ffffff;">
            <p>Do <strong>not</strong> change <code>HTTP_PORT</code>, <code>HTTPS_PORT</code>, <code>HTTP_BIND</code>, or <code>HTTPS_BIND</code>. Leaving them at their default values is crucial. Changing <code>HTTP_BIND</code> to <code>127.0.0.1</code> will prevent Traefik from reaching the Mailcow web UI, resulting in a <strong>404 Not Found error</strong>. The internal ports do not conflict with Traefik because they are inside the Docker network, not on the host.</p>

        </td>
    </tr>
</table>


1.  **Disable Mailcow's Let's Encrypt:** Traefik is responsible for all certificate management. This is the most important change.
    ```ini
    # Find this line:
    SKIP_LETS_ENCRYPT=n
    # Change it to:
    SKIP_LETS_ENCRYPT=y
    ```

2.  **Add SAN for Internal TLS:** This helps internal services correctly recognize the hostname on the certificate provided by the `certdumper`.
    ```ini
    # Find this line (it may be commented out):
    # ADDITIONAL_SAN=
    # Change it to:
    ADDITIONAL_SAN=${MAILCOW_HOSTNAME}
    ```

Save and close the file. No other changes are needed in this file.

### 5.3. Activate MTA-STS

MTA-STS (Mail Transfer Agent-Strict Transport Security) is a security standard that helps prevent man-in-the-middle attacks by ensuring emails are transmitted over secure TLS connections.

<!-- Infobox Shortcode - Retro-kompatibel mit Browsern der 90er Jahre -->
<!-- Verwendung: infobox(type="info", title="Titel") mit Inhalt der Box -->
<!-- Types: info, warning, tip, note -->


<table class="retro-infobox" width="100%" cellspacing="0" cellpadding="10" border="1">
    <tr>
        <td bgcolor="#ccffcc" style="color: #000000; font-weight: bold;">
            💡 
            EASIER ALTERNATIVE: USE THE MAILCOW UI
        </td>
    </tr>
    <tr>
        <td bgcolor="#000000" style="color: #ffffff;">
            <p>Instead of creating the policy file by hand, you can navigate to <strong>System -&gt; Configuration -&gt; MTA-STS</strong> in the Mailcow UI after setup. The UI provides a generator that creates the correct policy and DNS records for you, which is less error-prone. The manual method below is still valid if you prefer it.</p>

        </td>
    </tr>
</table>


If you choose the manual route, create the required directory:
```bash
sudo mkdir -p /opt/containers/mailcow/data/web/.well-known/

Now, create the policy file with a simple enforce policy. This file will be served by Mailcow’s web server.

sudo tee /opt/containers/mailcow/data/web/.well-known/mta-sts.txt > /dev/null << 'EOF'
version: STSv1
mode: enforce
max_age: 15552000
mx: mail.your-domain.com
EOF

sudo sed -i "s/your-domain.com/your-actual-domain.com/g" /opt/containers/mailcow/data/web/.well-known/mta-sts.txt

6. Launch Mailcow

You can now start the Mailcow stack.

cd /opt/containers/mailcow
docker compose up -d

7. DNS Configuration

Correct DNS setup is critical for a mail server to function.

7.1. Reverse DNS (PTR Record)

Your server’s Reverse DNS (PTR) record for both IPv4 and IPv6 must match the hostname you configured in mailcow.conf (mail.your-domain.com). This is usually set in your server provider’s control panel and is essential for not being marked as spam, especially by major providers like Gmail.

7.2. DNS Records

In your domain’s DNS management panel, add the following records. We start with a non-restrictive DMARC policy (p=none) to prevent legitimate emails from being rejected during the initial setup.

A DKIM record will be added later after it’s generated by Mailcow.

8. Firewall Configuration

Your firewall must allow traffic on several ports for email services to be reachable.

Use ufw to open these ports:

sudo ufw allow 25/tcp
sudo ufw allow 587/tcp
sudo ufw allow 465/tcp
sudo ufw allow 143/tcp
sudo ufw allow 993/tcp
sudo ufw allow 110/tcp
sudo ufw allow 995/tcp
sudo ufw allow 4190/tcp
sudo ufw status

9. Initial Mailcow Setup

Navigate to your Mailcow UI at https://mail.your-domain.com.

• Default Username: admin
• Default Password: moohoo

First, change the administrator password under System -> Configuration -> Edit.

9.1. Add Your Domain

Go to Email -> Configuration and click “Add domain”. Enter your main domain (e.g., your-domain.com, not mail.your-domain.com).

9.2. Generate DKIM Key

A DKIM key is essential for email authentication.

1. Go to System -> Configuration.

2. Navigate to the Options -> ARC/DKIM keys tab.

3. A 2048-bit key should already be generated for your domain. Copy the public key text from the text box.

4. Go back to your DNS provider and add a new TXT record:

   • Name: dkim._domainkey
   • Value: Paste the entire copied key, including the v=DKIM1;k=rsa;p=... part.

   💡 LONG DKIM RECORDS

   Some DNS providers have a 255-character limit for a single TXT record string. If your 2048-bit DKIM key is longer, you may need to split it into multiple quoted strings. Many providers handle this automatically, but if you encounter issues, check your provider’s documentation on how to format long TXT records.

10. Testing and Verification

After waiting for DNS propagation, thoroughly test your setup.

10.1. Internal DNS and Certificate Check

• Mailcow DNS Check: In the Mailcow UI, go to Email -> Configuration -> DNS next to your domain for an internal check of your records.
• Verify Certificates: Ensure that the certificates from Traefik have been correctly passed to Mailcow’s services. Run these commands, replacing mail.your-domain.com with your mail server’s FQDN:

  # Check SMTP certificate
  echo "Q" | openssl s_client -starttls smtp -crlf -connect mail.your-domain.com:587
  
  # Check IMAP certificate
  echo "Q" | openssl s_client -starttls imap -crlf -connect mail.your-domain.com:143
  

  In the output, look for a certificate chain issued by a trusted authority. For Let’s Encrypt, the chain typically starts with ISRG Root X1. The key is to confirm it is not a self-signed certificate. If you see a self-signed certificate (where the issuer matches the subject), it indicates a problem with the certdumper service or its path mappings. In that case, check the certdumper logs:

  cd /opt/containers/mailcow
  docker compose logs certdumper
  

10.2. External Testing Tools

• mail-tester.com: Send an email to the address provided on their site to get a score out of 10.
• mxtoolbox.com: Provides various checks for your mail server.
• checktls.com/TestReceiver: Use this to specifically verify your MTA-STS configuration.

11. Create Mailboxes and Log In

Under Email -> Mailboxes, you can add new users. Once a user is created, the primary way to access the webmail interface (SOGo) is by clicking Apps -> Webmail from within the Mailcow UI. While you can also try going directly to https://mail.your-domain.com/SOGo/, be aware that recent Mailcow versions may redirect unauthenticated access back to the main login page.

12. Conclusion

You have now successfully deployed a full-featured Mailcow e-mail server. By leveraging Docker for containerization and Traefik for reverse proxying and certificate management, you have a secure, robust, and maintainable mail solution. This setup provides you with complete control over your email, enhanced security through features like MTA-STS, and the flexibility to manage multiple domains and users with ease.

13. Further Reading

For more detailed information, refer to the official Mailcow documentation:

• Reverse Proxy Overview: docs.mailcow.email/post-installation/r_p-overview/
• IP Bindings: docs.mailcow.email/post-installation/firststeps-ip_bindings/
• MTA-STS Setup: docs.mailcow.email/post-installation/firststeps-mta_sts/