Postfix SMTP Server (F4.1)
1. Overview
Postfix SMTP Server provides enterprise-grade outgoing email transport (MTA) and mail submission for all domains managed in Vexlyx.
In production, port 587 presents the publicly trusted Let's Encrypt certificate for VEXLYX_MAIL_HOSTNAME. Traefik obtains and renews it, while system/scripts/install/sync-mail-tls.sh extracts the matching key pair from acme.json, installs it atomically in docker/mail-data/certs, and restarts Postfix and Dovecot only when the pair changes. A systemd timer runs that sync every 12 hours. The self-signed certificate generated by the container remains a development-only fallback.
The mail hostname must resolve to the Vexlyx server and ports 80/443 must be reachable for the initial HTTP-01 challenge. To retry after correcting DNS:
sudo /usr/local/sbin/vexlyx-sync-mail-tlsInbound delivery also requires an MX record at VEXLYX_MAIL_DOMAIN targeting VEXLYX_MAIL_HOSTNAME with priority 10. Both values are independently configurable; code and operator guidance must not assume they are always mail.$VEXLYX_DOMAIN and $VEXLYX_DOMAIN. PTR/reverse DNS is configured at the hosting provider, not by Vexlyx. Public mail operation also requires inbound TCP ports 25, 587 and 993, while outbound TCP/25 may require provider approval.
Drawing from modern cloud-native standards (Mailcow, Plesk, CloudPanel, Resend), Vexlyx decouples outgoing mail into:
- RFC 6409 Port Separation: Clear segregation between port 25 (server-to-server relay/delivery with strict open relay denial) and port 587 (authenticated client submission with mandatory TLS encryption).
- Cryptographic DKIM Signing via OpenDKIM: Automated 2048-bit RSA key pair generation per domain, auto-configuring
KeyTable,SigningTable, andTrustedHosts, with direct integration into Vexlyx CoreDNS (F3.3) for instant one-click DNS TXT record deployment. - Decoupled Virtual Domain Sync: Virtual domain tables (
/etc/postfix/virtual_domains,virtual_mailbox_maps) synchronized as flat hash maps viapostfix_manager.py, isolating mail delivery from runtime database schema changes. Pipelining (#158): Postfix 3.9 defaultssmtpd_forbid_unauth_pipeliningtoyes(an SMTP smuggling mitigation), so a client that sendsEHLOandQUITin one packet gets554 5.5.0 SMTP protocol synchronization. Mail clients do exactly that when probing a new account (Thunderbird), so thesubmissionservice indocker/postfix/master.cfsets-o smtpd_forbid_unauth_pipelining=no. That service only talks to clients that negotiate TLS and then authenticate; port 25, the one exposed to arbitrary senders, keeps the strict default.tests/test_postfix_submission_pipelining.pybuilds the image and sends a pipelined probe to both ports. - Hybrid Dev & Production Parity: Full containerized development environment in
docker-compose.yml(vexlyx-postfix) exposing ports 25 and 587, alongside a dedicated bare-metal production installer (system/scripts/setup-postfix.sh). - Interactive Diagnostic Sandbox: Real-time SMTP handshake testing and open relay verification directly within the Vexlyx dashboard.
2. Architecture & Data Flow
┌─────────────────────────────────────────────────────────────┐
│ Next.js Dashboard UI │
│ - /mail (Global Mail & Outgoing SMTP hub) │
│ - Daemon status & Port 25 / 587 health badges │
│ - Virtual domains accordion with DKIM DNS TXT copy helpers │
│ - Interactive SMTP Test Email & Anti-Relay Probe modals │
└──────────────────────────────┬──────────────────────────────┘
│ HTTP / JSON
▼
┌─────────────────────────────────────────────────────────────┐
│ Fastify API Server │
│ - GET /api/mail/status (Daemon & port status) │
│ - GET /api/mail/domains (List domains & DKIM state) │
│ - POST /api/mail/sync (Sync virtual domains) │
│ - POST /api/mail/dkim/:id (Generate DKIM / add to DNS) │
│ - POST /api/mail/test-send (Live SMTP test delivery) │
│ - GET /api/mail/test-relay (Probe open relay defense) │
└───────────────┬──────────────────────────────┬──────────────┘
│ │
▼ ▼
┌───────────────────────────────┐ ┌───────────────────────────┐
│ PostgreSQL (Prisma) │ │ system/python/ │
│ - model Domain │ │ postfix_manager.py │
│ - model DnsRecord │ │ - 2048-bit RSA DKIM keys │
│ - model Mailbox │ │ - sync virtual maps │
└───────────────────────────────┘ │ - handshake probing │
└─────────────┬─────────────┘
│ Configures
▼
┌───────────────────────────┐
│ Postfix & OpenDKIM Engine │
│ - Port 25 (SMTP MTA) │
│ - Port 587 (Submission) │
│ - Port 8891 (Milter) │
│ - Strict Anti-Open-Relay │
└───────────────────────────┘3. Configuration Specifications
Postfix main.cf (docker/postfix/main.cf)
# Identity
myhostname = mail.vexlyx.local
mydomain = vexlyx.local
myorigin = $mydomain
mydestination = localhost.$mydomain, localhost
inet_interfaces = all
inet_protocols = ipv4
# Virtual Domains & Mailboxes
virtual_mailbox_domains = /etc/postfix/virtual_domains
virtual_mailbox_maps = hash:/etc/postfix/virtual_mailbox_maps
virtual_alias_maps = hash:/etc/postfix/virtual_alias_maps
# Relay Security (No Open Relay)
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16
smtpd_relay_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination
# TLS Encryption
smtpd_tls_security_level = may
smtpd_tls_cert_file = /etc/postfix/certs/cert.pem
smtpd_tls_key_file = /etc/postfix/certs/key.pem
smtpd_tls_protocols = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1
smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1
# OpenDKIM Milter
smtpd_milters = inet:127.0.0.1:8891
non_smtpd_milters = $smtpd_milters
milter_default_action = accept
milter_protocol = 6Postfix master.cf (docker/postfix/master.cf)
# Standard SMTP MTA
smtp inet n - n - - smtpd
# Submission Port 587 (RFC 6409)
submission inet n - n - - smtpd
-o syslog_name=postfix/submission
-o smtpd_tls_security_level=encrypt
-o smtpd_sasl_auth_enable=yes
-o smtpd_reject_unlisted_recipient=no
-o smtpd_client_restrictions=permit_sasl_authenticated,permit_mynetworks,reject
-o smtpd_relay_restrictions=permit_sasl_authenticated,permit_mynetworks,reject
-o milter_macro_daemon_name=ORIGINATINGLookup map rebuilds (virtual_mailbox_maps, virtual_alias_maps) — failures are reported (#51)
Postfix reads the compiled .lmdb files, not the plain-text sources, so every mailbox/alias change must be recompiled with postmap. A failed rebuild leaves the previous map in place (recipients rejected with 550, mail routed to old destinations), so it is never swallowed:
| Where | Behaviour on a failed rebuild |
|---|---|
postfix_manager.py _compile_lmdb_map() | Checks the exit status (the script saves the postmap/mv/chmod chain's status before the cleanup rm, which would otherwise always report success), and raises PostfixMapError with the map name and the command's stderr. Timeouts and a missing docker binary are errors too. |
sync_virtual_domains / sync_virtual_aliases | The error propagates, no reload is attempted, and the script prints { "error", "code": "POSTFIX_MAP_COMPILE_FAILED" } with exit 1. |
MailService.syncVirtualDomains / syncVirtualAliases | Reject with MailError POSTFIX_MAP_COMPILE_FAILED (502) instead of treating the error payload as a result. |
POST /api/mail/sync | Returns that error. |
| Mailbox create / reset password / quota / delete | The database change is already committed, so a failed sync is not an error response (creation would otherwise lose the one-time password, and a saved change would look like a failure). The call succeeds and the response carries warnings: ["The change was saved, but the mail server could not be updated: … Use Mail → Sync to retry."] (DELETE returns 200 { success, warnings } instead of 204 only in this case). Creation is audited and the domain's first-mailbox SPF/DKIM/DMARC/MX setup still runs. The dashboard shows each warning as a toast. |
Container entrypoint.sh compile_map | A missing source file is still the quiet first-boot case. A compile failure logs ERROR: failed to compile <map>; a map whose source exists but whose .lmdb is missing afterwards, or that cannot be made world-readable, is logged as an error too, plus a startup warning. None of these abort startup. |
Tests: tests/test_postfix_map_rebuild.py, apps/api/src/modules/mail/sync.test.ts, apps/api/src/modules/mailboxes/service.test.ts.
4. OpenDKIM & DNS TXT Auto-Configuration
- Key Generation: 2048-bit RSA private keys are stored in
/etc/opendkim/keys/{domain}/{selector}.private. - OpenDKIM Configuration:
KeyTable:default._domainkey.domain.com domain.com:default:/etc/opendkim/keys/domain.com/default.privateSigningTable:*@domain.com default._domainkey.domain.comTrustedHosts: Local subnets and domain names.
- RFC 6376 DNS TXT Record:
- Record Name:
default._domainkey.domain.com - Record Value:
v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCA... - Auto-inserted into
model DnsRecordzone when CoreDNS (F3.3) is active.
- Record Name:
5. Testing & Verification
Run the dedicated test suite:
python tests/test_postfix_smtp.pyCovered tests:
test_01_generate_dkim_keys_and_dns_record: Verifies 2048-bit key generation andv=DKIM1; k=rsa; p=...format.test_02_opendkim_tables_updated: VerifiesKeyTable,SigningTable, andTrustedHosts.test_03_get_dkim_existing: Checks retrieving existing DKIM keys from disk.test_04_sync_virtual_domains: Verifies flat map creation for virtual domains and mailboxes.test_05_status_inspection: Verifies service status structure.test_01_main_cf_security_parameters: Checksmain.cfparameters.test_02_master_cf_submission_service: Checks port 587 submission parameters.test_03_opendkim_conf_parameters: Checksopendkim.conf.test_04_host_setup_script_exists: Validates VPS installation script.test_01_unauthenticated_requests_return_401: Enforces security on all mail endpoints.
6. How to Extend
- F4.2 Dovecot IMAP Server (🟢 COMPLETED): Postfix is configured with
smtpd_sasl_type = dovecotandsmtpd_sasl_path = inet:dovecot:12345(a TCP auth listener, not a shared unix socket — Postfix and Dovecot run in separate containers). Seedocs/dev/email/dovecot.md. - F4.3 Mailbox Management UI: The virtual mailbox map structure (
/etc/postfix/virtual_mailbox_maps) is ready for per-user quota and address provisioning. - F4.5 SPF & DMARC Auto-Configuration: The DKIM public keys generated in F4.1 directly populate the DMARC and SPF alignment policies.