1Postern
  2=======
  3
  4Subscribe to our mailing list by sending an email to `postern+subscribe@lists.p25.dev` for announcements of
  5new versions.
  6The mailing list server runs Postern and mlmmj.
  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
 14> **⚠️ WARNING:** This software is in an experimental state.
 15> Do not use in production or for any important emails while we work towards v1.0.
 16
 17Overview
 18--------
 19
 20What makes Postern special is its policy engine. Imagine it as a modern Sieve based on
 21[Starlark](https://starlark-lang.org), which uses Python syntax.
 22The [policy.star file](https://code.raphting.dev/postern.git/blob/main/policy.star) has an example how new senders end up in a "Gatekeeper" mailbox.
 23Simply moving a message from one folder to another updates how the policy engine reacts to this sender
 24for future messages.
 25
 26Reacting on side effects such as database state or network calls is probably the biggest advantage of the policy engine
 27over Sieve when it comes to modern email management.
 28
 29Postern has secure defaults, stores emails encrypted at rest and runs as a single binary with an SQLite backend.
 30This simplifies backups. All you need to back up is your `/var/lib/postern` (depending on your configuration) directory.
 31
 32You can subscribe to *announcements* by sending an email to `postern+subscribe@lists.p25.dev`.
 33The mailing list server runs on Postern and mlmmj.
 34
 35Architecture
 36------------
 37
 38Postern was developed for easy email self-hosting while not fighting email deliverability or a multitude of DNS records.
 39
 40Postern is designed to sit behind an email relay and MX backup like [p25.dev](https://p25.dev). With just 3 DNS records
 41(DKIM, MX and domain verification) you are ready for sending and receiving emails. Postern can run behind other services
 42such as Postfix too, as it is fully standards compliant. The main use case will be the operation 
 43behind [p25.dev](https://p25.dev) though just for its simplicity and to support more inexperienced admins in self-hosting
 44email.
 45
 46Your emails are stored encrypted in [Data At Rest Encryption (DARE) format](https://github.com/minio/sio).
 47Note that the SQLite database stores email _metadata_ such as To and From addresses and Subjects
 48in **plain text** to support fast IMAP search requests.
 49
 50All networking is secure by default. IMAP and SMTP Submission run on implicit TLS. SMTP Delivery requires
 51STARTTLS and authentication. Passwords are generated by Postern to avoid weak choices.
 52
 53DKIM key management is designed for easy key rotation.
 54
 55Quickstart
 56----------
 57
 58Postern is in alpha state. You might experience some trial and error to arrive at a working solution.
 59This quickstart tutorial assumes you work on a modern Linux installation.
 60Because you read this Readme, it looks like you have access to the rest of the source code and can compile it with
 61`go build -o postern .`.
 62
 631. Install the `postern.service` file under `/etc/systemd/system/postern.service`.
 642. Place `policy.star` under `/etc/postern/policy.star` and adjust to your requirements.
 653. For secure storage of the masterkey,
 66   run `systemd-ask-password -n | systemd-creds encrypt - /etc/credstore/masterkey`
 674. Retrieve a TLS certificate, for example with [acme.sh](https://github.com/acmesh-official/acme.sh).
 68   Make sure the systemd service can access the certificates (`/etc/postern/`).
 695. Enable and start Postern `systemctl enable postern` and `systemctl start postern`
 706. Use the Postern CLI to add configuration. Based on the systemd integration, this is admittedly clunky
 71   and will be improved soon.
 72
 73When running the Postern CLI, it will communicate with the **running** Postern daemon over a unix socket.
 74The used socket is logged during startup and can be configured with environment variable `POSTERN_SOCKET`.
 75
 76```Shell
 77export POSTERN_SOCKET=/run/postern/postern.sock
 78/usr/local/bin/postern
 79```
 80
 81### CLI admin access
 82
 83Unix sockets have an Owner and a Group like any other file on Unix or Linux.
 84Instead of creating an admin user and a password in Postern, access is guarded by existing Unix file permissions.
 85
 86*root* should always have access. The systemd Postern user also has access, even though in the default configuration
 87it is dynamically created by systemd.
 88
 89If you want to use a non-root and non-Postern user for the CLI, have the systemd service run under a specific group
 90that your non-root user also belongs to.
 91
 92### First configuration steps (example)
 93
 94You will need to create a user, a backup-mx user for email delivery and a DKIM key.
 95
 96```Shell
 97postern user add testuser
 98postern user add-address testuser user@example.com
 99postern backup-mx add p25dev
100postern dkim add selector example.com # Don't forget to enable the key with 'dkim enable selector example.com'
101```
102
103If you want a smooth start for sending and receiving emails, make an account at [p25.dev](https://p25.dev) to integrate
104Postern with it.
105
106Contributing via Mailing List
107-----------------------------
108
109We manage development via plain-text email patches rather than web-based pull requests.
110
111**Mailing list:** `postern-dev@lists.p25.dev` (subscribe with an email to `postern-dev+subscribe@lists.p25.dev`)
112
113Use `git send-email` to contribute your patch. For a tutorial see [https://git-send-email.io](https://git-send-email.io/).
114It is okay to use the mailing list as a chat rather than a formalized procedure. Just say 'hi'!
115
116> **💡 TIP:** You can integrate `git send-email` with Postern too!
117
118Security
119--------
120
121Please do not disclose security vulnerabilities via the public mailing list.
122Instead, use `https://p25.dev/.well-known/security.txt`