feat: add Mailu template

Mailu 2024.06 mail server: front (nginx), admin, imap (dovecot), smtp (postfix), antispam (rspamd), Roundcube webmail and redis. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-22 22:35:24 +02:00 · 2026-07-16 17:50:38 -06:00
parent a3f2655baa
commit f6245f84dc
5 changed files with 344 additions and 0 deletions
--- a/blueprints/mailu/docker-compose.yml
+++ b/blueprints/mailu/docker-compose.yml
@@ -0,0 +1,146 @@
+version: "3.8"
+
+# Shared Mailu configuration (equivalent to the upstream mailu.env file)
+x-mailu-env: &mailu-env
+  - SECRET_KEY=${SECRET_KEY}
+  - DOMAIN=${DOMAIN}
+  - HOSTNAMES=${DOMAIN}
+  - POSTMASTER=admin
+  # TLS for the mail protocols is obtained through Let's Encrypt (HTTP-01
+  # through Traefik on port 80). The web UI itself is served plain HTTP to
+  # Traefik, which terminates HTTPS.
+  - TLS_FLAVOR=mail-letsencrypt
+  # Mailu grants relay/XCLIENT trust to this network range. It must cover the
+  # Docker networks of this project (Docker allocates them from 172.16.0.0/12
+  # by default). Narrow it down if you know your exact subnet.
+  - SUBNET=${SUBNET}
+  - ADMIN=true
+  - WEBMAIL=roundcube
+  - API=false
+  - WEBDAV=none
+  - ANTIVIRUS=none
+  - SCAN_MACROS=false
+  # Ports enabled inside the front container. 4190 (sieve) stays internal for
+  # the webmail filters UI and is not published on the host.
+  - PORTS=25,80,443,465,587,993,4190
+  - MESSAGE_SIZE_LIMIT=50000000
+  - FULL_TEXT_SEARCH=en
+  - WEBROOT_REDIRECT=/webmail
+  - WEB_ADMIN=/admin
+  - WEB_WEBMAIL=/webmail
+  - SITENAME=Mailu
+  - WEBSITE=https://mailu.io
+  # Trust Traefik (dokploy-network) to forward the real client IP for rate limiting
+  - REAL_IP_FROM=${SUBNET}
+  - REAL_IP_HEADER=X-Forwarded-For
+  # Initial admin account: admin@${DOMAIN} (created only if it does not exist)
+  - INITIAL_ADMIN_ACCOUNT=${INITIAL_ADMIN_ACCOUNT}
+  - INITIAL_ADMIN_DOMAIN=${DOMAIN}
+  - INITIAL_ADMIN_PW=${INITIAL_ADMIN_PW}
+  - INITIAL_ADMIN_MODE=ifmissing
+
+# Public DNSSEC-validating resolvers. The admin container refuses to start
+# without DNSSEC validation, and Postfix needs it for outbound DANE. Service
+# discovery still uses Docker's embedded DNS; these are only upstreams.
+x-mailu-dns: &mailu-dns
+  - "1.1.1.1"
+  - "8.8.8.8"
+
+services:
+  front:
+    image: ghcr.io/mailu/nginx:2024.06
+    restart: unless-stopped
+    environment: *mailu-env
+    dns: *mailu-dns
+    # Mail protocol ports are published directly on the host (same approach as
+    # the poste.io template). They will fail to bind if another mail server
+    # already uses them on this machine.
+    ports:
+      - "25:25" # SMTP (server to server)
+      - "465:465" # SMTPS submission
+      - "587:587" # Submission (STARTTLS)
+      - "993:993" # IMAPS
+    volumes:
+      - mailu-certs:/certs
+    # The image's built-in healthcheck also requires the mail (Dovecot) proxy,
+    # which only starts once TLS certificates exist. Behind Traefik that
+    # deadlocks: unhealthy -> Traefik drops the route -> the ACME challenge can
+    # never be answered. Check only nginx instead (health endpoint returns 204).
+    healthcheck:
+      test: ["CMD-SHELL", "curl -m3 -skfLo /dev/null http://127.0.0.1:10204/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 60s
+    depends_on:
+      - admin
+
+  admin:
+    image: ghcr.io/mailu/admin:2024.06
+    restart: unless-stopped
+    environment: *mailu-env
+    dns: *mailu-dns
+    volumes:
+      - mailu-data:/data
+      - mailu-dkim:/dkim
+    depends_on:
+      - redis
+
+  imap:
+    image: ghcr.io/mailu/dovecot:2024.06
+    restart: unless-stopped
+    environment: *mailu-env
+    dns: *mailu-dns
+    volumes:
+      - mailu-mail:/mail
+    depends_on:
+      - front
+
+  smtp:
+    image: ghcr.io/mailu/postfix:2024.06
+    restart: unless-stopped
+    environment: *mailu-env
+    dns: *mailu-dns
+    volumes:
+      - mailu-mailqueue:/queue
+    depends_on:
+      - front
+
+  antispam:
+    image: ghcr.io/mailu/rspamd:2024.06
+    restart: unless-stopped
+    hostname: antispam
+    environment: *mailu-env
+    dns: *mailu-dns
+    volumes:
+      - mailu-filter:/var/lib/rspamd
+    depends_on:
+      - front
+      - redis
+
+  webmail:
+    image: ghcr.io/mailu/webmail:2024.06
+    restart: unless-stopped
+    environment: *mailu-env
+    dns: *mailu-dns
+    volumes:
+      - mailu-webmail:/data
+    depends_on:
+      - front
+      - imap
+
+  redis:
+    image: redis:alpine
+    restart: unless-stopped
+    volumes:
+      - mailu-redis:/data
+
+volumes:
+  mailu-certs: {}
+  mailu-data: {}
+  mailu-dkim: {}
+  mailu-mail: {}
+  mailu-mailqueue: {}
+  mailu-filter: {}
+  mailu-webmail: {}
+  mailu-redis: {}
--- a/blueprints/mailu/instructions.md
+++ b/blueprints/mailu/instructions.md
@@ -0,0 +1,23 @@
+# Mailu
+
+## Getting started
+
+1. Point the domain you assign in Dokploy (for example `mail.example.com`) at your server **before** deploying: an `A` record, plus an `MX` record for your mail domain targeting it.
+2. Deploy the template and open the domain: `/webmail` is Roundcube, `/admin` is the admin UI.
+3. Log in at `/admin` with `admin@<your domain>` and the auto-generated `INITIAL_ADMIN_PW` (Dokploy → your service → Environment). The account is created only on first boot (`INITIAL_ADMIN_MODE=ifmissing`); change the password from the admin UI afterwards.
+4. In the admin UI, open **Mail domains → your domain → Details** and create the DNS records it shows (SPF, DKIM, DMARC). Also set the **PTR/reverse DNS** record of your server IP to your mail hostname — most providers require this to accept your mail.
+
+## Ports
+
+The mail protocol ports are published directly on the host: **25** (SMTP), **465** (SMTPS), **587** (submission) and **993** (IMAPS). The deployment fails to start if another mail server (or a previous Mailu deployment) already binds them on the same machine. Many VPS providers block outbound port 25 by default — ask your provider to unblock it, or configure a relay host in Mailu.
+
+## TLS
+
+- The web UI is served through Traefik like any other Dokploy app. Enable **HTTPS with Let's Encrypt** on the Dokploy domain: the web login cookie requires HTTPS, and Mailu's internal certbot self-check follows Traefik's HTTP→HTTPS redirect and needs a valid certificate there.
+- The mail ports get their own Let's Encrypt certificate: the `front` container runs certbot internally and answers the HTTP-01 challenge through Traefik on port 80. This only succeeds once the DNS record of your domain points at the server. If the certificate was obtained *after* the first boot, restart the `front` service once so the TLS mail listeners (465/587/993) come up.
+
+## Notes
+
+- `SUBNET` (default `172.16.0.0/12`) is the network range Mailu trusts for its internal traffic (Postfix relay/XCLIENT, Dovecot proxying, Rspamd). It covers Docker's default address pools; if your Docker daemon uses custom pools, adjust it to match. Note this means other containers on the same Docker host are treated as trusted senders.
+- The containers use public DNSSEC-validating resolvers (`1.1.1.1`, `8.8.8.8`) as upstream DNS: the admin container requires DNSSEC validation and Postfix uses it for DANE. Heavy production use benefits from a dedicated local resolver instead, because public resolvers are rate-limited by DNSBLs (see the [Mailu DNS FAQ](https://mailu.io/2024.06/faq.html)).
+- Additional mail domains, users, aliases and fetchmail can be managed in the admin UI. ClamAV antivirus is not included in this template to keep memory usage low (it needs >1 GB RAM); see the Mailu docs to add it.
--- a/blueprints/mailu/mailu.svg
+++ b/blueprints/mailu/mailu.svg
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="210mm"
+   height="297mm"
+   viewBox="0 0 744.09448819 1052.3622047"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.91 r13725"
+   sodipodi:docname="logo.svg">
+  <defs
+     id="defs4">
+    <path
+       style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;direction:ltr;block-progression:tb;writing-mode:lr-tb;baseline-shift:baseline;text-anchor:start;white-space:normal;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"
+       d="m 263.62305,623.95312 -0.95703,0.28907 c 0,0 8.73472,28.99871 31.14453,57.99219 22.40981,28.99347 58.55631,58.02539 113.28125,58.02539 109.39431,0 155.50976,-97.76563 155.50976,-97.76563 l -0.90429,-0.42578 c 0,0 -45.80684,97.19141 -154.60547,97.19141 -54.37155,0 -90.2008,-28.79897 -112.49024,-57.63672 -22.28944,-28.83775 -30.97851,-57.66993 -30.97851,-57.66993 z"
+       id="path4142-3"
+       inkscape:connector-curvature="0" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.7"
+     inkscape:cx="77.860065"
+     inkscape:cy="631.62981"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1920"
+     inkscape:window-height="1080"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <circle
+       style="fill:none;stroke:#000000;stroke-width:15;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="path4136"
+       cx="416.00003"
+       cy="574.93365"
+       r="196.7318" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:40px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="297.14285"
+       y="609.79077"
+       id="text4138"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4140"
+         x="297.14285"
+         y="609.79077"
+         style="font-size:90px">Mailu</tspan></text>
+    <path
+       style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;direction:ltr;block-progression:tb;writing-mode:lr-tb;baseline-shift:baseline;text-anchor:start;white-space:normal;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"
+       d="m 263.62305,623.95312 -0.95703,0.28907 c 0,0 8.73472,28.99871 31.14453,57.99219 22.40981,28.99347 58.55631,58.02539 113.28125,58.02539 109.39431,0 155.50976,-97.76563 155.50976,-97.76563 l -0.90429,-0.42578 c 0,0 -45.80684,97.19141 -154.60547,97.19141 -54.37155,0 -90.2008,-28.79897 -112.49024,-57.63672 -22.28944,-28.83775 -30.97851,-57.66993 -30.97851,-57.66993 z"
+       id="path4142"
+       inkscape:connector-curvature="0" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:40px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;"
+       id="text4144"
+       sodipodi:linespacing="125%"><textPath
+         xlink:href="#path4142"
+         id="textPath4150"><tspan
+   id="tspan4146"
+   style="fill:#000000;fill-opacity:1;">  email since 2016</tspan></textPath></text>
+    <path
+       style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;direction:ltr;block-progression:tb;writing-mode:lr-tb;baseline-shift:baseline;text-anchor:start;white-space:normal;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"
+       d="m 275.13574,527.65954 -0.91835,-0.23149 c 0,0 8.38171,-23.22244 29.88583,-46.44069 21.50412,-23.21824 56.18977,-46.46727 108.70301,-46.46727 104.97317,0 149.22487,78.29163 149.22487,78.29163 l -0.86774,0.34096 c 0,0 -43.95557,-77.83178 -148.35713,-77.83178 -52.17413,0 -86.55535,23.06248 -107.94397,46.15602 -21.38862,23.09354 -29.72652,46.18262 -29.72652,46.18262 z"
+       id="path4184"
+       inkscape:connector-curvature="0" />
+    <text
+       y="-623.17346"
+       x="-262.66602"
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:40px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       id="text4144-6"
+       sodipodi:linespacing="125%"
+       transform="translate(404.56768,384.57019)"><textPath
+         xlink:href="#path4142-3"
+         id="textPath4150-7"><tspan
+   id="tspan4146-5"
+   style="fill:#000000;fill-opacity:1">  email since 2016</tspan></textPath></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:40px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       id="text4203"
+       sodipodi:linespacing="125%"
+       x="-2"
+       transform="translate(-4,10)"><textPath
+         xlink:href="#path4184"
+         id="textPath4207"><tspan
+   id="tspan4205">delivering insular</tspan></textPath></text>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:4;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:0.61572051;stroke-miterlimit:4;stroke-dasharray:none"
+       d="m 228.79956,370.50924 c 0,0 113.13708,-21.21321 163.13963,81.82235 50.00255,103.03556 58.08377,183.34269 168.1904,213.14219 110.10663,29.7995 99.50003,25.75889 99.50003,25.75889"
+       id="path4214"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:4;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:0.61572051"
+       d="m 210.94153,406.39617 c 0,0 113.13708,-21.21321 163.13963,81.82235 50.00255,103.03556 58.08377,183.34269 168.1904,213.14219 110.10663,29.7995 99.50003,25.75889 99.50003,25.75889"
+       id="path4230-3"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:4;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:0.61572051"
+       d="m 192.75878,438.21597 c 0,0 113.13708,-21.21321 163.13963,81.82235 50.00255,103.03556 58.08377,183.34269 168.1904,213.14219 110.10663,29.7995 99.50003,25.75889 99.50003,25.75889"
+       id="path4230-3-5"
+       inkscape:connector-curvature="0" />
+  </g>
+</svg>
--- a/blueprints/mailu/meta.json
+++ b/blueprints/mailu/meta.json
@@ -0,0 +1,21 @@
+{
+  "id": "mailu",
+  "name": "Mailu",
+  "version": "2024.06",
+  "description": "Full-featured open-source mail server as a set of Docker containers: SMTP (Postfix), IMAP (Dovecot), Rspamd antispam, admin UI with DKIM management and Roundcube webmail.",
+  "logo": "mailu.svg",
+  "links": {
+    "github": "https://github.com/Mailu/Mailu",
+    "website": "https://mailu.io/",
+    "docs": "https://mailu.io/2024.06/",
+    "docker": "https://github.com/orgs/Mailu/packages"
+  },
+  "tags": [
+    "email",
+    "mail-server",
+    "smtp",
+    "imap",
+    "antispam",
+    "webmail"
+  ]
+}
--- a/blueprints/mailu/template.toml
+++ b/blueprints/mailu/template.toml
@@ -0,0 +1,17 @@
+[variables]
+main_domain = "${domain}"
+secret_key = "${password:16}"
+admin_password = "${password:32}"
+
+[config]
+[[config.domains]]
+serviceName = "front"
+port = 80
+host = "${main_domain}"
+
+[config.env]
+DOMAIN = "${main_domain}"
+SECRET_KEY = "${secret_key}"
+INITIAL_ADMIN_ACCOUNT = "admin"
+INITIAL_ADMIN_PW = "${admin_password}"
+SUBNET = "172.16.0.0/12"