Self-Hosted SimpleLogin (2026)
SimpleLogin is an email-alias service: you give it a
domain, generate per-site aliases like mountain-rhino-2941@simplymail.org,
and it forwards inbound mail to your real mailbox. Reply to the forwarded
message and SimpleLogin sends it out as the alias, so the other side never
learns your real address. The community self-hosts it under simplymail.org.
What’s in this guide
Section titled “What’s in this guide”| Section | What you’ll find |
|---|---|
| The alias model | How forwarding and reverse-alias replies work |
| Architecture | The five containers and how mail flows between them |
| Public DNS layout | A, MX, SPF, DKIM, DMARC, MTA-STS and TLS-RPT, and the unproxied-MX rule |
| Public MX binding | IP binding, firewall, ports and FQDN |
| TLS, relay and Postfix hardening | Inbound certificate, the RELAY_HOST bracket trap, relay TLS policy, MYNETWORKS, VRFY |
| Authentik OIDC | Client config, email-based account linking, the alternative_id trap, the apex-cookie fix |
| In-network delivery to mailcow | A transport_maps override for domains hosted next door |
| Reply gating | Authorized addresses and the Apple Mail picker trap |
| Host-level networking traps | Multi-homed egress routing, Cloudflare dormant rules |
| Operational gotchas | Backscatter from unknown aliases, the unsaved queue, connection pools, upgrades |
| End-to-end verification | A swaks probe and what the logs should show |
End-user docs (making aliases, browser extensions, mobile apps) are at simplelogin.io. This page covers what their docs don’t: the self-hosted architecture as deployed, and the gotchas that have bitten us.
Why SimpleLogin (not just Cloudflare Email Routing)
Section titled “Why SimpleLogin (not just Cloudflare Email Routing)”| Need | Cloudflare Email Routing | SimpleLogin (self-hosted) |
|---|---|---|
Forward info@yourdomain to one inbox | Yes, free and simple | Overkill |
| A different alias for every site you sign up to | No (each one made by hand) | Yes, purpose-built |
| Reply from the alias so the other side never sees your address | No | Yes, through reverse aliases |
| Who handles the mail | Cloudflare | Your server receives it. Forwards to outside mailboxes and replies leave through your relay (Amazon SES for us), which sees the envelope, headers and content. Delivery to a mailbox on your own mail server stays in-house. |
| Browser extension that creates aliases on the fly | No | Yes |
| Alias dashboard, per-alias on/off, contact rules | No | Yes |
| MFA, OIDC login and an audit log for the alias account | No | Yes |
Email Routing solves “I want info@ in my Gmail.” SimpleLogin solves “every
service I sign up to gets its own address, which I can switch off without
losing anything else.” The two coexist fine on different domains.
The alias model
Section titled “The alias model”Sender (for example orders@shop.example) │ ▼ simplymail.org MX → sl-postfix: queue, validate, hand off │ ▼ sl-email: - look up mountain-rhino-2941@simplymail.org → its alias - look up the alias → its mailbox (you@example.com) - create or find a Contact for the original sender - rewrite From: to a per-contact "reverse alias" │ ▼ out through the relay (Amazon SES) → you@example.com
------------------------------------------------------------Reply path (you press Reply):
you@example.com │ replies to the reverse alias @simplymail.org ▼ simplymail.org MX → same listener │ sl-email: - look up the reverse alias → the original Contact - check MAIL FROM is one of the mailbox's authorized addresses - rewrite From: → mountain-rhino-2941@simplymail.org │ ▼ out to orders@shop.example (they only ever see the alias)The reverse alias is the trick. Each (alias, contact) pair gets its own random-looking address, which is how SimpleLogin knows which alias and which contact a reply belongs to.
Architecture
Section titled “Architecture”| Container | Image | Role |
|---|---|---|
sl-postfix | simplelogin/postfix | The public MX. Accepts mail for *@simplymail.org and hands it to sl-email. Relays outbound mail through the smarthost (Amazon SES), except for domains in the in-network transport map. |
sl-email | simplelogin/app-ci | The handler: alias lookup, contact creation, reverse aliases, forwarding and replies. Internal only. |
sl-app | simplelogin/app-ci | The Flask web app at app.simplymail.org: login (Authentik OIDC), dashboard, alias creation. Listens on loopback, published through a Cloudflare Tunnel. |
sl-job-runner | simplelogin/app-ci | Background jobs, such as “spoof attempt blocked” notices. |
sl-db | postgres:16-alpine (pinned by digest) | Users, mailboxes, aliases, contacts and logs. Internal only. |
Pin all three app-ci containers to the same version, and pin
simplelogin/postfix to an exact version too. The five containers share a private
Docker network; only sl-postfix:25 is public.
Outbound mail goes through a smarthost: ours is Amazon SES since 2026-10-20 (Brevo before). The MX IP has no reverse DNS of its own, and the relay’s warm reputation handles deliverability, so a low-volume alias service doesn’t have to build IP reputation. The trade-off: the relay is a third party in the path for anything that leaves the host, so pick one that doesn’t modify mail. Brevo rewrote links and added tracking images to every HTML forward; SES passes messages through unchanged (see App and transactional mail). Whatever relay you use, verify the alias domain with it, or it will refuse forwards sent as reverse aliases.
Public DNS layout
Section titled “Public DNS layout”A mx.simplymail.org <public-ip> proxied=falseMX simplymail.org mx.simplymail.org pri=10TXT simplymail.org "v=spf1 ip4:<public-ip> ~all"TXT dkim._domainkey <SimpleLogin's own DKIM public key, 2048-bit>CNAME <token>._domainkey ×3 <token>.dkim.amazonses.com proxied=false (SES Easy DKIM)TXT _dmarc.simplymail.org "v=DMARC1; p=quarantine; sp=quarantine; rua=mailto:<reports-address>"TXT _mta-sts.simplymail.org "v=STSv1; id=<change-this-on-every-policy-change>"A/CNAME mta-sts.simplymail.org <wherever the policy file is served over HTTPS>TXT _smtp._tls.simplymail.org "v=TLSRPTv1; rua=mailto:<reports-address>"CNAME app.simplymail.org <tunnel-id>.cfargotunnel.com proxied=trueCNAME api.simplymail.org <tunnel-id>.cfargotunnel.com proxied=true- SPF: with Amazon SES’s default envelope sender (an
amazonses.comaddress), receivers check SES’s SPF, not yours, so noinclude:is needed. If your relay uses your domain as the envelope sender, include its documented sending ranges. Brevo notes: useinclude:spf.brevo.com;include:sendinblue.comis Brevo’s corporate record and also authorises Google, Zendesk and Intercom, and_spf.brevo.compublishesv=spf1 -alland authorises nothing. - DKIM: SimpleLogin signs with its own key (
dkim._domainkey), and the relay adds its own aligned signature: SES Easy DKIM’s three CNAMEs (Brevo’s would bebrevo1/brevo2). Either aligned signature passes DMARC. - DMARC: set
sp=too, so subdomains can’t be spoofed under a weaker policy, and make sure theruaaddress really exists (a report from another domain also needs an authorisation record; see Email DNS and authentication). - MTA-STS and TLS-RPT: publish them once inbound TLS works (next sections). Start
the policy in
testingmode.
The mx A record must be proxied=false (grey cloud). Cloudflare’s proxy
carries HTTP only, so SMTP through it doesn’t work. The dashboard creates new A
records as proxied; the API doesn’t. Check after creating.
The dashboard and API hostnames go through the tunnel, which is fine: they’re HTTP.
Public MX binding — the parts that have to line up
Section titled “Public MX binding — the parts that have to line up”Putting sl-postfix:25 on a public IP takes five separate pieces, and each one
fails on its own when it’s missing.
1. The IP is bound on the host’s bridge
Section titled “1. The IP is bound on the host’s bridge”The secondary IP must actually be on the host’s interface (vmbr0 on Proxmox).
If it’s only routed to you, Docker fails to start the container with
cannot assign requested address.
ip addr add <public-ip>/<prefix> dev vmbr0 label vmbr0:slarping -A -c 3 -I vmbr0 <public-ip> # gratuitous ARP so the upstream router learns it# Persist both lines as `up` commands in /etc/network/interfaces.2. Outbound from the SimpleLogin network is allowed
Section titled “2. Outbound from the SimpleLogin network is allowed”On a host whose DOCKER-USER chain ends in DROP, a Docker network outside the
default ranges has no internet access. sl-app then can’t reach Authentik, and
sl-postfix can’t reach the relay.
Symptom: sl-app is unhealthy, and /auth/oidc/login returns 500 with
Temporary failure in name resolution for the identity provider, while the host
itself reaches it fine.
Allow egress from that network to the uplink only, and persist the rule:
iptables -I DOCKER-USER -s <sl-network-subnet> -o vmbr0 \ -m comment --comment "SimpleLogin egress" -j ACCEPTDon’t use a bare -s <subnet> -j ACCEPT: it also skips Docker’s isolation
between networks.
3. Inbound port 25 to the public IP is allowed
Section titled “3. Inbound port 25 to the public IP is allowed”Docker publishes the listener, but conntrack-based DOCKER-USER rules drop
outside traffic until there’s an explicit ACCEPT for that IP and port:
iptables -I DOCKER-USER -p tcp -m conntrack \ --ctorigdst <public-ip> --ctorigdstport 25 \ -m comment --comment "SimpleLogin postfix :25" -j ACCEPT4. The compose port binding names the IP
Section titled “4. The compose port binding names the IP”sl-postfix: ports: - "<public-ip>:25:25"Apply it with docker compose up -d, which recreates the container. A
restart doesn’t pick up port changes. Publish nothing else: the internal
hand-off port to sl-email stays on the private network.
5. POSTFIX_FQDN matches the A record
Section titled “5. POSTFIX_FQDN matches the A record”The HELO/EHLO banner reports POSTFIX_FQDN. Set it to the A record’s name so
receivers’ forward-confirmed reverse DNS checks pass:
sl-postfix: environment: POSTFIX_FQDN: mx.simplymail.orgAsk your provider for a PTR record for the IP pointing at the same name. That’s baseline for any MX, not an extra.
Once all five are in place, check from outside:
swaks --server mx.simplymail.org --port 25 \ --to <any-active-alias>@simplymail.org \ --from probe@<a-real-domain> \ --quit-after FIRST-HELO# Expect "220 mx.simplymail.org ESMTP Postfix", then the EHLO capabilities.TLS, relay and Postfix hardening
Section titled “TLS, relay and Postfix hardening”Inbound TLS needs a real certificate
Section titled “Inbound TLS needs a real certificate”Without a certificate, sl-postfix silently turns STARTTLS off and alias mail
arrives in plaintext. The image’s certbot fallback needs port 80 published to
the container, which a tunnel-fronted setup doesn’t have. Issue the certificate
another way (we use acme.sh with a DNS-01 challenge and a Cloudflare token scoped to
the one zone), mount it read-only, point TLS_CERT_FILE/TLS_KEY_FILE at it, and
have the renewal hook reload Postfix.
Check it from outside:
openssl s_client -starttls smtp -connect mx.simplymail.org:25 \ -servername mx.simplymail.org -verify_hostname mx.simplymail.org </dev/null# Expect "Verify return code: 0 (ok)".The RELAY_HOST bracket trap
Section titled “The RELAY_HOST bracket trap”Set RELAY_HOST to the bare name (for SES, email-smtp.<region>.amazonaws.com). The
image’s template adds the square brackets itself; with brackets in your compose it renders
[[smtp-relay.brevo.com]]:587 (our Brevo-era mistake), the Postfix smtp client dies at start-up
(garbage after "]"), and nothing is relayed: no forwards to outside mailboxes,
no replies, no account mail. The deferred queue shows those messages with an
empty reason, which is easy to miss. Our wrapper entrypoint now refuses to start when
RELAY_HOST is empty or contains a bracket, so this fails loudly instead.
Make the relay prove who it is
Section titled “Make the relay prove who it is”Postfix’s default for a relay is opportunistic TLS, so a network attacker could downgrade the connection and capture the relay login. Require a verified certificate for the relay only:
smtp_tls_policy_maps = inline:{ [email-smtp.us-east-2.amazonaws.com]:587=secure }Because the image regenerates main.cf at every start, set this from the wrapper
entrypoint (see below).
Trust nothing but your own network
Section titled “Trust nothing but your own network”Set MYNETWORKS explicitly to the SimpleLogin network (minus its gateway). Left
unset, the image trusts every network the container is attached to, and anything
on those networks can relay through it unauthenticated.
Smaller things
Section titled “Smaller things”- Disable
VRFY(disable_vrfy_command = yes), so the MX can’t be used to probe which addresses exist. - Spamhaus DQS: set
POSTFIX_DQN_KEYif you have a free DQS key; public DNS resolvers get refused by Spamhaus. - DKIM: generate a 2048-bit key; move DMARC towards
p=rejectonce reports are clean.
Authentik OIDC
Section titled “Authentik OIDC”The OIDC client settings live in simplelogin.env on the host:
URL=https://app.simplymail.orgOIDC_CLIENT_ID=<from Authentik>OIDC_CLIENT_SECRET=<from Authentik>OIDC_WELL_KNOWN_URL=https://<authentik-host>/application/o/<app-slug>/.well-known/openid-configurationIn Authentik: an OAuth2/OIDC provider and application, with the redirect URI
https://app.simplymail.org/auth/oidc/callback. sl-app must be able to reach
Authentik over HTTPS, which is why the egress rule in step 2 matters. Set
OAUTHLIB_RELAX_TOKEN_SCOPE=1, because Authentik returns scopes in a different order
from the request.
Apex vs canonical host: the cookie split
Section titled “Apex vs canonical host: the cookie split”URL=https://app.simplymail.org is the canonical host. The Flask session cookie
that holds the OIDC state is set on exactly that host.
If the apex simplymail.org also serves sl-app, a user who starts the login on
the apex gets the state cookie there. Authentik then sends them back to
app.simplymail.org/auth/oidc/callback, which can’t see the cookie, and the
callback fails with oauthlib.MismatchingStateError (a 500).
Two fixes:
-
Redirect the apex at the edge (recommended). No tunnel route for the apex; a Cloudflare Single Redirect rule sends every request to
https://app.simplymail.org. One canonical host owns sessions.Terminal window curl -X POST -H "Authorization: Bearer $CF_API_TOKEN" \-H "Content-Type: application/json" \"https://api.cloudflare.com/client/v4/zones/$ZONE/rulesets/phases/http_request_dynamic_redirect/entrypoint" \-d '{"rules": [{"action": "redirect","action_parameters": {"from_value": {"status_code": 301,"target_url": {"expression": "concat(\"https://app.simplymail.org\", http.request.uri.path)"},"preserve_query_string": true}},"expression": "(http.host eq \"simplymail.org\")"}]}'If the apex also serves the MTA-STS policy host or other names, scope the expression to
http.host eq "simplymail.org"exactly, as above. -
Widen the cookie domain with
SESSION_COOKIE_DOMAIN=.simplymail.org. Both hosts then share the cookie, and so does every other subdomain. That’s fine only if you control them all.
alternative_id must be set on every user
Section titled “alternative_id must be set on every user”Flask-Login stores session['_user_id'] = user.get_id(), and get_id() returns
alternative_id (a UUID) when it’s set, otherwise the integer primary key. With
alternative_id NULL, the next request looks up alternative_id="2", finds
nothing, and the session silently dies: the user lands back on the login page.
This only bites after bulk SQL imports that bypass User.create(). After any
direct database insert, check and backfill:
SELECT id, alternative_id FROM users WHERE alternative_id IS NULL;-- if any:UPDATE users SET alternative_id = gen_random_uuid()::textWHERE alternative_id IS NULL;In-network delivery to mailcow (skip Brevo for hosted domains)
Section titled “In-network delivery to mailcow (skip Brevo for hosted domains)”Some aliases belong to people whose real mailbox is on our own mail server,
mailcow (irregulars.io). For those, sl-postfix
delivers straight to mailcow’s Postfix over an internal Docker network on the
host, instead of sending the message out through the relay and back in through the
MX. That takes a third party out of the metadata path.
Why a route override instead of merging Postfix instances
Section titled “Why a route override instead of merging Postfix instances”Many guides (for example simple-login/app#765 and docker-mailserver#2380) merge SimpleLogin into one big Postfix. We keep two independent Postfix instances and connect them with a transport map:
| Reason | Why two instances win |
|---|---|
| Different security domains | mailcow holds real mailboxes; SimpleLogin rewrites public-facing aliases. Mixing them lets a mistake in one affect the other. |
| Independent upgrades | mailcow and simplelogin/postfix release on different schedules. Merged, one upgrade can break the other. |
| Separate reputations | simplymail.org and mailcow’s domains each have their own DKIM and their own relay identity. |
| Easy to remove | Dropping SimpleLogin means deleting its containers. mailcow is untouched. |
How the override works
Section titled “How the override works”sl-postfix’s transport_maps becomes a chain, and the first match wins:
transport_maps = pgsql:/etc/postfix/pgsql-transport-maps.cf, # SimpleLogin alias domains → sl-email texthash:/srv/postfix-extra/transport-extra # hosted domains → mailcow directly# relayhost = [email-smtp.us-east-2.amazonaws.com]:587 # everything else → SESThe transport-extra file:
irregulars.io smtp:[postfix-mailcow]:25The square brackets turn off the MX lookup, so Postfix connects straight to that
host. Docker’s DNS resolves postfix-mailcow on the shared network.
Wrapping the entrypoint (why main.cf can’t be patched directly)
Section titled “Wrapping the entrypoint (why main.cf can’t be patched directly)”The simplelogin/postfix entrypoint runs generate_config.py --postfix at every
start, which regenerates main.cf from a Jinja template. A bind mount over
main.cf would be overwritten, and the template has no transport_maps setting.
The fix is a small wrapper entrypoint script that:
- Repeats upstream’s start-up flow, with
POSTFIX_CUSTOM_DATA_DIRECTORYexported (trap 2 below). - Runs
generate_config.py --postfix, so the stock config is correct. - Adds the overrides with
postconf -e: thetransport_mapschain, the relay TLS policy, and anything else the template lacks. - Execs
postfix start-fg.
Compose mounts the wrapper and the flat file:
sl-postfix: volumes: - ./postfix-extra/entrypoint-override.sh:/usr/local/bin/entrypoint-override.sh:ro - ./postfix-extra/transport-extra:/srv/postfix-extra/transport-extra:ro command: ["/usr/local/bin/entrypoint-override.sh"]Diff the wrapper against upstream’s entrypoint after every image bump.
Three traps
Section titled “Three traps”-
The
hash:driver isn’t shipped.simplelogin/postfixis Alpine-based, and Alpine deprecated BerkeleyDB.postconf -mlistslmdb,texthash,inlineandregexp, but nothash(upstream: simplelogin-postfix-docker#7).lmdb:needs a writable directory for its compiled file, which a read-only bind mount doesn’t give it.texthash:reads the flat file in place, with nopostmapand no compiled database. Its trade-off: no change detection (Postfix DATABASE_README). -
POSTFIX_CUSTOM_DATA_DIRECTORYmust be exported, not just assigned. Upstream exports it. If the wrapper only assigns it,generate_config.py --postfixsilently fails to writepgsql-transport-maps.cf(Jinja’sStrictUndefinedraises inside that step). Symptom:postfix start-fglogsopen "pgsql" configuration: No such file or directoryfor every daemon, and mail to*@simplymail.orgstops resolving. -
Don’t bind-mount inside
/etc/postfix/. Postfix’s start-up check warnsnot owned by rootfor any file there not owned by UID 0, and a host-mounted file belongs to a host user. Mount it under/srv/postfix-extra/and use the absolute path.
Adding a domain
Section titled “Adding a domain”Edit transport-extra on the host, then recreate the container (drain the queue
first; see the unsaved queue):
docker compose up -d --force-recreate sl-postfixtransport-extra is a single-file bind mount. Most editors (and sed -i) write a
new file rather than changing the old one in place, and the container keeps
reading the old one. postfix reload doesn’t help in that case; recreating does.
Verifying the route
Section titled “Verifying the route”Delivery lines should show mailcow’s Postfix as the relay:
docker logs sl-postfix --since 5m 2>&1 | grep 'to=<.*@irregulars.io>'# expected: relay=postfix-mailcow[...]:25# wrong: relay=email-smtp.<region>.amazonaws.com[...]:587 (the outbound relay)Before adding a domain, check that any mailbox actually uses it. SimpleLogin
forwards to mailbox.email, not users.email:
docker exec sl-db psql -U <db-user> -d simplelogin -c \ "SELECT split_part(email,'@',2), COUNT(*) FROM mailbox GROUP BY 1 ORDER BY 2 DESC;"Reply gating — authorized addresses
Section titled “Reply gating — authorized addresses”When the alias owner replies through a reverse alias, sl-email checks that the
envelope MAIL FROM is either the mailbox’s own address or one of its
authorized addresses. Anything else is rejected with
250 SL E214 Unauthorized for using reverse alias, and the owner gets a “spoof
attempt blocked” notice with a one-click “Allow” link.
This is anti-spoofing: without it, anyone who guessed a reverse alias could send as your aliases.
Adding an authorized address
Section titled “Adding an authorized address”In the app: click “Allow” in the notice. SimpleLogin verifies the address by email before activating it.
As the operator (skips verification; only for addresses you know the owner controls):
INSERT INTO authorized_address (created_at, user_id, mailbox_id, email)VALUES (NOW(), <user_id>, <mailbox_id>, '<address>')ON CONFLICT ON CONSTRAINT uq_authorize_address DO NOTHING;Then restart sl-email, which caches mailbox lookups in memory:
docker restart sl-email.
The Apple Mail “From:” picker trap
Section titled “The Apple Mail “From:” picker trap”Apple Mail offers every identity in the account. When you reply to a forwarded message it defaults to the mailbox that received it. If you pick a different “From:”, the reply is rejected unless that address is authorized. Authorize each identity you reply from once.
Host-level networking traps
Section titled “Host-level networking traps”Both of these break mail flow without showing anything in SimpleLogin’s logs. Diagnosing them means going to the host.
Multi-homed egress routing
Section titled “Multi-homed egress routing”If the host has two uplinks on one interface (a residential line and a business IP block, say), the default route points at one of them. Replies from a container bound to an IP on the other uplink then leave through the wrong gateway and are dropped. Inbound SYNs arrive, the SYN-ACK never reaches the sender, and no SMTP session ever starts.
Symptom: no RCPT TO from real senders in sl-postfix’s logs, only the
odd scanner. Senders see deferrals and, eventually, bounces.
Fix: policy routing keyed on the input interface (the Docker bridge), not the source IP, because the kernel picks the return route before NAT rewrites the source. Run it as a boot-time service that re-reads the bridge names, which change when a network is recreated. More detail: mailcow § Lessons learned.
Cloudflare Email Routing dormant rules
Section titled “Cloudflare Email Routing dormant rules”Turning off Cloudflare Email Routing for a zone doesn’t delete its forwarding rules. They stay enabled in the API and keep catching mail from senders that cached the old MX. A SimpleLogin domain shouldn’t have Email Routing on at all. The audit-and-delete commands are in mailcow § Lessons learned.
Operational gotchas
Section titled “Operational gotchas”Bounces to unknown aliases are backscatter your relay refuses
Section titled “Bounces to unknown aliases are backscatter your relay refuses”SimpleLogin’s Postfix accepts mail for any address at the alias domain, then
sl-email rejects unknown aliases (550 SL E515 Email not exist). Because Postfix
already accepted the message, it generates a bounce (a DSN with the null sender
<>) to the original sender, who is often forged by a spammer. A monitoring probe
sent to a non-existent alias produces the same thing.
Relays generally won’t take null-sender mail (Brevo refused it at MAIL FROM with
451 4.0.0 Invalid from), so those bounces sit in the deferred queue for days,
retrying, until Postfix’s bounce lifetime expires. In the logs this looks like an
outbound outage: a steady stream of relay deferrals. It isn’t. Real forwards and replies
can be flowing fine next to it.
Before you conclude the relay is broken, check the envelope sender of the deferred mail:
docker exec sl-postfix postqueue -j | python3 -c 'import json,sysfor l in sys.stdin: m=json.loads(l); s=m.get("sender") or "<>" print(m["queue_id"], "sender:", s.split("@")[-1], "|", m["recipients"][0].get("delay_reason","")[:80])'# Only "<>" senders deferred with "Invalid from" = backscatter, not an outage.Better options than letting them pile up:
- reject unknown aliases at SMTP time, before Postfix accepts the message (a recipient check against SimpleLogin’s database), so no bounce is ever generated;
- or don’t relay null-sender DSNs through the smarthost (shorten
bounce_queue_lifetime, or route them elsewhere).
Either way, sending bounces to forged senders hurts your reputation; avoid it where you can.
The queue isn’t on a volume
Section titled “The queue isn’t on a volume”sl-postfix’s mail queue lives inside the container. Recreating it discards
deferred mail (we lost 9 messages that way). Before any --force-recreate or image
bump, check postqueue -p and let it drain, or mount the queue on a volume.
Recreating sl-db breaks the apps’ connection pools
Section titled “Recreating sl-db breaks the apps’ connection pools”After docker compose up -d --force-recreate sl-db (a routine Postgres update),
sl-email keeps pooled connections to the old container. The next message
arrives, sl-postfix answers 250 to the sender, sl-email throws
psycopg2.OperationalError: server closed the connection unexpectedly, and the
message is lost.
Restart the app containers after any database recreate:
docker restart sl-email sl-app sl-job-runnerBetter: stop the app containers, recreate the database, then start them.
Upgrading SimpleLogin
Section titled “Upgrading SimpleLogin”Only the latest minor release gets security fixes, and they’re often not announced as such, so take minor releases promptly.
# 0. Pick a quiet moment: sl-postfix queue empty, no pending jobs, no dashboard traffic.
# 1. Back up the database to a file on the host, and check the dumpdocker exec sl-db pg_dump -Fc -U <db-user> simplelogin > sl-db-$(date +%Y%m%d).dumppg_restore --list sl-db-$(date +%Y%m%d).dump | head
# 2. Change the app-ci tag for all three app containers in docker-compose.yml, then:docker compose up -d --no-deps sl-app sl-email sl-job-runner
# 3. Apply migrationsdocker exec sl-app alembic upgrade head
# 4. Checkdocker ps --filter "name=sl-" --format "{{.Names}}\t{{.Status}}"curl -sS -o /dev/null -w "/auth/oidc/login → %{http_code}\n" http://127.0.0.1:<sl-app-port>/auth/oidc/loginRead every changelog entry between the running version and the target first, and compare the migrations. Then send a real test message through each path (forward, reply, delivery to a hosted domain).
End-to-end verification
Section titled “End-to-end verification”After any change to the receive path:
# A. Follow both handlersdocker logs -f sl-postfix --since 5s | sed "s/^/[postfix] /" &docker logs -f sl-email --since 5s | sed "s/^/[email] /" &
# B. Send a probeswaks --to <alias>@simplymail.org --from probe@<your-real-domain> \ --server mx.simplymail.org --port 25 \ --h-Subject "verify $(date +%s)"
# C. Within a second, sl-email should log:# "New message, mail from probe@... rctp tos ['<alias>@simplymail.org']"# "Forward <Contact X> -> <Alias Y> -> <Mailbox Z>"# "Finish ... return code '250 Message accepted for delivery'"Handy commands:
docker ps --filter "name=sl-" --format "{{.Names}}\t{{.Status}}"docker logs sl-email --tail 50docker exec sl-app alembic currentdocker logs sl-postfix 2>&1 | grep 'status=sent' | tail -5docker logs for sl-postfix can go stale silently. Compare the last line’s
timestamp with the clock (docker logs --timestamps sl-postfix | tail -1) before
trusting an empty grep.
Forking this stack (what to change)
Section titled “Forking this stack (what to change)”To stand up your own instance:
| File | Change |
|---|---|
.env | SL_DB_PASSWORD (generate it from letters and digits, so Compose doesn’t mangle a $), and the relay: SL_RELAY_HOST (a bare hostname), SL_RELAY_PORT, SL_RELAY_USERNAME, SL_RELAY_PASSWORD |
docker-compose.yml | The public IP in the sl-postfix port binding, POSTFIX_FQDN, MYNETWORKS, the certificate paths |
postfix-extra/transport-extra | Your own hosted domains, or none (an empty file loads and matches nothing) |
| DNS | Everything in Public DNS layout: the unproxied mx A record, MX, SPF with your IP (plus your relay’s include if it uses your domain as envelope sender), SimpleLogin’s DKIM and your relay’s DKIM, DMARC with sp=, then MTA-STS and TLS-RPT |
| Your ISP | A PTR record for the MX IP, matching POSTFIX_FQDN |
| Authentik | Provider, application (limited to one group) and the redirect URI https://app.<your-domain>/auth/oidc/callback; users can’t change their own email |
| Host firewall | The egress rule and the inbound port-25 rule from Public MX binding |
Worth adding once it’s stable:
- the apex →
app.<your-domain>redirect (cookie split); - egress policy routing if the host is multi-homed;
- SMTP-time rejection of unknown aliases (backscatter).
Related
Section titled “Related”- Running your own email: the overview and decision guide.
- Self-Hosted Mail Server: mailcow: the mail server SimpleLogin delivers into.
- Email DNS and authentication: SPF, DKIM, DMARC, MTA-STS and TLS-RPT in depth.
- Email deliverability and monitoring: what to watch once it’s running.
- Email Anonymity Guide: aliases from the user’s side.
References
Section titled “References”- SimpleLogin docs
- SimpleLogin on GitHub: source and changelog
- SimpleLogin security policy
- SimpleLogin self-hosting guide
- simplelogin/postfix Dockerfile
- Postfix DATABASE_README: lookup table types (texthash, lmdb, hash)
- Postfix STANDARD_CONFIGURATION_README: selective transport delivery
- Postfix TLS_README: per-destination TLS policy