1Postern
  2=======
  3
  4> [!WARNING]
  5> **Alpha warning:** This software is in an experimental state.
  6> Do not use in production or for any important emails while we work towards v1.0.
  7
  8Postern is a modern all-in-one mail delivery agent. It combines IMAP (IMAP4rev2),
  9SMTP Submission and SMTP delivery.
 10
 11We have EU Sovereignity at our core values. We welcome users and contributions from around the world and will keep
 12service providers such as server hosting and DNS registrars EU based.
 13
 14Overview
 15--------
 16
 17What makes Postern special is its policy engine. Imagine it as a modern Sieve based on
 18[Starlark](https://starlark-lang.org), which uses Python syntax.
 19The `policy.star` file has an example how new senders end up in a "Gatekeeper" mailbox.
 20Simply moving a message from one folder to another updates how the policy engine reacts to this sender
 21for future messages.
 22
 23Reacting on side effects such as database state or network calls is probably the biggest advantage of the policy engine
 24over Sieve when it comes to modern email management.
 25
 26Postern has secure defaults, stores emails encrypted at rest and runs as a single binary with an SQLite backend.
 27
 28You can subscribe to *announcements* by sending an email to `postern+subscribe@lists.p25.dev`.
 29The mailing list server runs on Postern and mlmmj.
 30
 31Architecture
 32------------
 33
 34Postern was developed for easy email self-hosting while not fighting email deliverability or a multitude of DNS records.
 35
 36Postern is designed to sit behind an email relay and MX backup like [p25.dev](https://p25.dev). With just 3 DNS records
 37(DKIM, MX and domain verification) you are ready for sending and receiving emails. Postern can run behind other services
 38such as Postfix too, as it is fully standards compliant. The main use case will be the operation 
 39behind [p25.dev](https://p25.dev) though just for its simplicity and to support more inexperienced admins in self-hosting
 40email.
 41
 42Your emails are stored encrypted in [Data At Rest Encryption (DARE) format](https://github.com/minio/sio).
 43Note that the SQLite database stores email _metadata_ such as To and From addresses and Subjects
 44in **plain text** to support fast IMAP search requests.
 45
 46All networking is secure by default. IMAP and SMTP Submission run on implicit TLS. SMTP Delivery requires
 47STARTTLS and authentication. Passwords are generated by Postern to avoid weak choices.
 48
 49DKIM key management is designed for easy key rotation.
 50
 51Quickstart
 52----------
 53
 54Postern is in alpha state. You might experience some trial and error to arrive at a working solution.
 55This quickstart tutorial assumes you work on a modern Linux installation.
 56Because you read this Readme, it looks like you have access to the rest of the source code and can compile it with
 57`go build -o postern .`.
 58
 591. Install the `postern.service` file under `/etc/systemd/system/postern.service`.
 602. Place `policy.star` under `/etc/postern/policy.star` and adjust to your requirements.
 613. For secure storage of the masterkey,
 62   run `systemd-ask-password -n | systemd-creds encrypt - /etc/credstore/masterkey`
 634. Retrieve a TLS certificate, for example with [acme.sh](https://github.com/acmesh-official/acme.sh).
 64   Make sure the systemd service can access the certificates (`/etc/postern/`).
 655. Enable and start Postern `systemctl enable postern` and `systemctl start postern`
 666. Use the Postern CLI to add configuration. Based on the systemd integration, this is admittedly clunky
 67   and will be improved soon.
 68
 69```Shell
 70# The masterkey file is only decrypted with a running postern service and only accessible by root.
 71# (this needs to be changed soon)
 72CONFIGURATION_DIRECTORY=/etc/postern POSTERN_PERSISTENCE_DIR=/var/lib/postern POSTERN_MASTERKEY_FILE=/run/credentials/postern.service/masterkey /usr/local/bin/postern
 73```
 74
 75You will need to create a user, a backup-mx user for email delivery and a DKIM key.
 76
 77```Shell
 78postern user add testuser
 79postern user add-address testuser user@example.com
 80postern backup-mx add p25dev
 81postern dkim add selector example.com # Don't forget to enable the key with 'dkim enable selector example.com'
 82```
 83
 84If you want a smooth start for sending and receiving emails, make an account at [p25.dev](https://p25.dev) to integrate
 85Postern with it.
 86
 87Contributing via Mailing List
 88-----------------------------
 89
 90We manage development via plain-text email patches rather than web-based pull requests.
 91
 92**Mailing list:** `postern-dev@lists.p25.dev` (subscribe with an email to `postern-dev+subscribe@lists.p25.dev`)
 93
 94Use `git send-email` to contribute your patch. For a tutorial see [https://git-send-email.io](https://git-send-email.io/).
 95It is okay to use the mailing list as a chat rather than a formalized procedure. Just say 'hi'!
 96
 97> [!TIP]
 98> You can integrate `git send-email` with Postern too!
 99
100Security
101--------
102
103Please do not disclose security vulnerabilities via the public mailing list.
104Instead, use `https://p25.dev/.well-known/security.txt`