computer-playbook/roles/web-app-mailu/README.md

Mailu

🪦 End of life. The project no longer maintains or tests this role; use it at your own risk and turn to upstream Mailu for support. Mailu is superseded by web-app-stalwart, the default email provider. New deployments MUST NOT adopt it and existing ones MUST migrate. Follow Migration from Mailu to move the mailboxes over. Until then, set MAIL_PROVIDER: web-app-mailu to keep routing the mail abstraction (plugins/lookup/email.py, sys-svc-mail) to Mailu.

Description

Revolutionize your email communications with Mailu, a secure and flexible mail server solution that integrates comprehensive features like robust SMTP/IMAP support, advanced spam filtering, DKIM signing, and seamless webmail access. With its modern design and performance-oriented architecture, Mailu empowers you to manage digital correspondence with efficiency and reliability.

Overview

Mailu is a complete mail server suite delivered as a Docker-based solution. It supports all essential email protocols, offers intuitive administration through a web interface, and integrates advanced security measures such as TLS encryption and virus scanning. Its modular architecture allows for scalable deployments and easy customization to suit diverse operational requirements.

More information about this role is available in these GitHub repositories:

• Mailu
• Mailu-OIDC

Cosmos

The diagram places Mailu in the Infinito.Nexus cosmos: the components it deploys (capabilities), the central services it consumes (dependencies), and its outward reach (federation and bridged external networks).

flowchart LR
    subgraph deps [Dependencies]
        dep_svc_bkp_volume_2_local["svc-bkp-volume-2-local 💻"]
        dep_svc_db_mariadb["svc-db-mariadb 🐳🐝"]
        dep_svc_db_redis["svc-db-redis 🐳🐝"]
        dep_svc_net_tor["svc-net-tor 🐳🐝"]
        dep_web_app_dashboard["web-app-dashboard 🐳🐝"]
        dep_web_app_keycloak["web-app-keycloak 🐳🐝"]
        dep_web_app_matomo["web-app-matomo 🐳🐝"]
        dep_web_app_prometheus["web-app-prometheus 🐳🐝"]
        dep_web_app_stalwart["web-app-stalwart 🐳🐝"]
        dep_web_svc_css["web-svc-css 💻"]
        dep_web_svc_logout["web-svc-logout 🐳🐝"]
    end
    subgraph role [web-app-mailu 🐳🐝]
        svc_sso["sso"]
        svc_logout["logout"]
        svc_dashboard["dashboard"]
        svc_matomo["matomo"]
        svc_email["email"]
        svc_mailu["mailu"]
        svc_redis["redis"]
        svc_unbound["unbound"]
        svc_mariadb["mariadb"]
        svc_admin["admin"]
        svc_imap["imap"]
        svc_smtp["smtp"]
        svc_antispam["antispam"]
        svc_antivirus["antivirus"]
        svc_oletools["oletools"]
        svc_webdav["webdav"]
        svc_fetchmail["fetchmail"]
        svc_webmail["webmail"]
        svc_front["front"]
        svc_css["css"]
        svc_prometheus["prometheus"]
        svc_tor["tor"]
        svc_container_backup["container_backup"]
    end
    dep_svc_bkp_volume_2_local -. "0..1" .-> svc_container_backup
    dep_svc_db_mariadb -. "0..1" .-> svc_mariadb
    dep_svc_db_redis -. "0..1" .-> svc_redis
    dep_svc_net_tor -. "0..1" .-> svc_tor
    dep_web_app_dashboard -. "0..1" .-> svc_dashboard
    dep_web_app_keycloak -. "0..1" .-> svc_sso
    dep_web_app_matomo -. "0..1" .-> svc_matomo
    dep_web_app_prometheus -. "0..1" .-> svc_prometheus
    dep_web_app_stalwart -. "0..1" .-> svc_email
    dep_web_svc_css -. "0..1" .-> svc_css
    dep_web_svc_logout -. "0..1" .-> svc_logout

Solid 1:1 edges are fixed relationships; dashed 0..1 edges are conditional (enabled only in matching deployments); red 0..0 edges are turned off in this role. Node markers show the role's deploy modes (💻 host, 🐳 compose, 🐝 swarm); ❌ marks a service that is explicitly turned off, and ⚙️ an Ansible role dependency declared in meta/main.yml.

Features

• Comprehensive Email Protocols: Supports SMTP, IMAP, and POP3 for reliable email delivery and retrieval.
• Advanced Security: Incorporates TLS encryption, DKIM, and SPF to secure your communications and prevent spoofing.
• Integrated Spam Filtering and Antivirus: Offers robust tools for spam detection and virus scanning, ensuring your inboxes remain clean and secure.
• Customizable Webmail and Administration: Provides a modern web interface for managing emails and administrative tasks with ease.
• Flexible Deployment: Easily scale and customize using Docker Compose, with configurable settings for networking, storage, and external services.
• OIDC Support: Optionally integrate with OpenID Connect for centralized authentication across your services.
• DMARC Reports: The published _dmarc record sends aggregate reports (rua) to <username>@<mail domain> of the user key in services.mailu.dmarc.rua_user (administrator unless the inventory names another one). That user MUST carry a mailbox account or a forward to a user that carries one and whose email is that mailbox (<username>@<mail domain>), otherwise the deploy fails before any record is written.

Quick Setup

Development

Clone, set up the workstation, and deploy Mailu onto the local stack:

git clone https://github.com/infinito-nexus/core.git
cd core
make onboard
make compose-deploy mode=reinstall apps=web-app-mailu full_cycle=false

Production

Run the published image to provision the inventory and deploy Mailu to a managed server (the mounted volume persists the inventory):

APP=web-app-mailu
HOST=<your-server>
DOMAIN=<your-domain>
TLS_MODE=self_signed
SSH_PUBLIC_KEY="<your-ssh-public-key>"

docker run --rm -it \
  -v "$PWD/inventories:/etc/infinito.nexus/inventories" \
  -e APP="$APP" -e HOST="$HOST" -e DOMAIN="$DOMAIN" -e TLS_MODE="$TLS_MODE" -e SSH_PUBLIC_KEY="$SSH_PUBLIC_KEY" \
  ghcr.io/infinito-nexus/core/debian bash -c '
    INVENTORY=/etc/infinito.nexus/inventories/production
    infinito administration inventory provision "$INVENTORY" \
      --inventory-file "$INVENTORY/devices.yml" \
      --host "$HOST" \
      --include "$APP" \
      --vars "{\"TLS_MODE\": \"$TLS_MODE\", \"DOMAIN_PRIMARY\": \"$DOMAIN\", \"users\": {\"administrator\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}}}" &&
    infinito administration deploy dedicated "$INVENTORY/devices.yml" \
      --password-file "$INVENTORY/.password" \
      --diff -vv'

Further Resources

• Mailu Official Website
• Mailu compose setup guide
• SysPass issue #1299
• Mailu issue #1719
• Mailu issue #1171
• Mailu issue #2135
• Mailu issue #2827
• Mailu GitHub repository
• Gist by marienfressinaud

Persona contract opt-outs

This role declares PERSONA_ADMINISTRATOR_BLOCKED and PERSONA_BIBER_BLOCKED in templates/playwright.env.j2. Mailu's OIDC fork interposes its own /sso/login page that carries a local login form next to an openid-connect/auth link, while the authenticated Roundcube surface carries an openid-connect/logout link; the shared helper matches login controls by accessible name and cannot tell the two apart, so it clicks logout. The administrator persona is blocked for a second, independent reason: Mailu's admin surface is a separate Flask app mounted at WEB_ADMIN=/admin (templates/env.j2), not the /webmail/ surface the OIDC callback lands on.

Both journeys are covered bespoke in files/playwright/playwright.spec.js, which targets the openid-connect/auth href explicitly, opens /admin, and signs out at /admin/ui/logout; a second scenario drives the biber-to-administrator mail round-trip across two browser contexts. The path back to the generic personas is a distinguishable login control on Mailu's SSO page.

Credits

Implemented by Kevin Veen-Birkenbach. Part of the Infinito.Nexus Project and maintained by Kevin Veen-Birkenbach. Licensed under the Infinito.Nexus Community License (Non-Commercial).