docs: Remove section about use of objects

- Revised cmdeploy documentation in doc/source/overview.rst to reflect
  the recent revisions to the Deployer interface.

.github/workflows/docs-preview.yaml

@@ -0,0 +1,80 @@
+name: documentation preview
+
+on:
+  pull_request:
+    paths:
+      - 'doc/**'
+      - 'scripts/build-docs.sh'
+      - '.github/workflows/docs-preview.yaml'
+
+jobs:
+  scripts:
+    name: build 
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: initenv 
+        run: scripts/initenv.sh
+
+      - name: append venv/bin to PATH
+        run: echo `pwd`/venv/bin >>$GITHUB_PATH
+
+      - name: build documentation 
+        working-directory: doc
+        run: sphinx-build source build
+
+      - name: build documentation second time (for TOC)
+        working-directory: doc
+        run: sphinx-build source build
+
+      - name: Get Pullrequest ID
+        id: prepare
+        run: |
+          export PULLREQUEST_ID=$(echo "${{ github.ref }}" | cut -d "/" -f3)
+          echo "prid=$PULLREQUEST_ID" >> $GITHUB_OUTPUT
+          if [ $(expr length "${{ secrets.USERNAME }}") -gt "1" ]; then echo "uploadtoserver=true" >> $GITHUB_OUTPUT; fi
+      - run: |
+          echo "baseurl: /${{ steps.prepare.outputs.prid }}" >> _config.yml
+
+      - name: Upload preview
+        run: |
+          mkdir -p "$HOME/.ssh"
+          echo "${{ secrets.CHATMAIL_STAGING_SSHKEY }}" > "$HOME/.ssh/key"
+          chmod 600 "$HOME/.ssh/key"
+          rsync -rILvh -e "ssh -i $HOME/.ssh/key -o StrictHostKeyChecking=no" $GITHUB_WORKSPACE/doc/build/ "${{ secrets.USERNAME }}@chatmail.at:/var/www/html/staging.chatmail.at/doc/relay/${{ steps.prepare.outputs.prid }}/"
+
+      - name: "Post links to details"
+        id: details
+        if: steps.prepare.outputs.uploadtoserver
+        run: |
+          # URLs for API connection and uploads
+          export GITHUB_API_URL="https://api.github.com/repos/chatmail/relay/statuses/${{ github.event.after }}"
+          export PREVIEW_LINK="https://staging.chatmail.at/doc/relay/${{ steps.prepare.outputs.prid }}/"
+          export STATUS_DATA="{\"state\": \"success\", \
+                               \"description\": \"Preview the changed documentation here:\", \
+                               \"context\": \"Documentation Preview\", \
+                               \"target_url\": \"${PREVIEW_LINK}\"}"
+          curl -X POST --header "Accept: application/vnd.github+json" --header "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" --url "$GITHUB_API_URL" --header "content-type: application/json" --data "$STATUS_DATA"
+
+          #check if comment already exists, if not post it
+          export GITHUB_API_URL="https://api.github.com/repos/chatmail/relay/issues/${{ steps.prepare.outputs.prid }}/comments"
+          export RESPONSE=$(curl -L --header "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" --url "$GITHUB_API_URL" --header "content-type: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28")
+          echo $RESPONSE > response
+          grep -v '"Check out the page preview at https://staging.chatmail.at/doc/relay' response && echo "comment=true" >> $GITHUB_OUTPUT || true
+      - name: "Post link to comments"
+        if: steps.details.outputs.comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: "Check out the page preview at https://staging.chatmail.at/doc/relay/${{ steps.prepare.outputs.prid }}/"
+            })
+
+      - name: check links 
+        working-directory: doc
+        run: sphinx-build --builder linkcheck source build
+

.github/workflows/docs.yaml

@@ -0,0 +1,44 @@
+name: build and upload documentation
+
+on:
+  push:
+    branches:
+      - main
+      - 'missytake/docs-ci'
+    paths:
+      - 'doc/**'
+      - 'scripts/build-docs.sh'
+      - '.github/workflows/docs.yaml'
+
+jobs:
+  scripts:
+    name: build 
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: initenv 
+        run: scripts/initenv.sh
+
+      - name: append venv/bin to PATH
+        run: echo `pwd`/venv/bin >>$GITHUB_PATH
+
+      - name: build documentation 
+        working-directory: doc
+        run: sphinx-build source build
+
+      - name: build documentation second time (for TOC)
+        working-directory: doc
+        run: sphinx-build source build
+
+      - name: check links 
+        working-directory: doc
+        run: sphinx-build --builder linkcheck source build
+
+      - name: upload documentation
+        run: |
+          mkdir -p "$HOME/.ssh"
+          echo "${{ secrets.CHATMAIL_STAGING_SSHKEY }}" > "$HOME/.ssh/key"
+          chmod 600 "$HOME/.ssh/key"
+          rsync -rILvh -e "ssh -i $HOME/.ssh/key -o StrictHostKeyChecking=no" $GITHUB_WORKSPACE/doc/build/ "${{ secrets.USERNAME }}@chatmail.at:/var/www/html/chatmail.at/doc/relay/"
+

.github/workflows/test-and-deploy-ipv4only.yaml

@@ -20,7 +20,7 @@ jobs:
       group: ci-ipv4-${{ github.workflow }}-${{ github.ref }}
       cancel-in-progress: ${{ !contains(github.ref, '$GITHUB_REF') }}
     steps:
-      - uses: jsok/serialize-workflow-action@v1
+      - uses: jsok/serialize-workflow-action@515cd04c46d7ea7435c4a22a3b4419127afdefe9
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
       - uses: actions/checkout@v4

.github/workflows/test-and-deploy.yaml

@@ -20,7 +20,7 @@ jobs:
       group: ci-${{ github.workflow }}-${{ github.ref }}
       cancel-in-progress: ${{ !contains(github.ref, '$GITHUB_REF') }}
     steps:
-      - uses: jsok/serialize-workflow-action@v1
+      - uses: jsok/serialize-workflow-action@515cd04c46d7ea7435c4a22a3b4419127afdefe9
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
       - uses: actions/checkout@v4

ARCHITECTURE.md

@@ -1,50 +0,0 @@
-This diagram shows components of the chatmail server; this is a draft
-overview as of mid-August 2025:
-
-```mermaid
-graph LR;
-    cmdeploy --- sshd;
-    letsencrypt --- |80|acmetool-redirector;
-    acmetool-redirector --- |443|nginx-right(["`nginx
-    (external)`"]);
-    nginx-external --- |465|postfix;
-    nginx-external(["`nginx
-    (external)`"]) --- |8443|nginx-internal["`nginx
-    (internal)`"];
-    nginx-internal --- website["`Website
-    /var/www/html`"];
-    nginx-internal --- newemail.py;
-    nginx-internal --- autoconfig.xml;
-    certs-nginx[("`TLS certs
-    /var/lib/acme`")] --> nginx-internal;
-    cron --- chatmail-metrics;
-    cron --- acmetool;
-    chatmail-metrics --- website;
-    acmetool --> certs[("`TLS certs
-    /var/lib/acme`")];
-    nginx-external --- |993|dovecot;
-    autoconfig.xml --- postfix;
-    autoconfig.xml --- dovecot;
-    postfix --- echobot;
-    postfix --- |10080,10081|filtermail;
-    postfix --- users["`User data
-    home/vmail/mail`"];
-    postfix --- |doveauth.socket|doveauth;
-    dovecot --- |doveauth.socket|doveauth;
-    dovecot --- users;
-    dovecot --- |metadata.socket|chatmail-metadata;
-    doveauth --- users;
-    chatmail-expire-daily --- users;
-    chatmail-fsreport-daily --- users;
-    chatmail-metadata --- iroh-relay;
-    certs-nginx --> postfix;
-    certs-nginx --> dovecot;
-    style certs fill:#ff6;
-    style certs-nginx fill:#ff6;
-    style nginx-external fill:#fc9;
-    style nginx-right fill:#fc9;
-```
-
-The edges in this graph should not be taken too literally; they
-reflect some sort of communication path or dependency relationship
-between components of the chatmail server.

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## untagged
 
+- Organized cmdeploy into install, configure, and activate stages
+  ([#695](https://github.com/chatmail/relay/pull/695))
+
+- docs: move readme.md docs to sphinx documentation rendered at https://chatmail.at/doc/relay 
+  ([#711](https://github.com/chatmail/relay/pull/711))
+
+- acmetool: replace cronjob with a systemd timer
+  ([#719](https://github.com/chatmail/relay/pull/719))
+
+- remove xstore@testrun.org from default passthrough recipients
+  ([#722](https://github.com/chatmail/relay/pull/722))
+
+- don't deploy the website if there are merge conflicts in the www folder
+  ([#714](https://github.com/chatmail/relay/pull/714))
+
 - acmetool: use ECDSA keys instead of RSA
   ([#689](https://github.com/chatmail/relay/pull/689))
 

README.md

@@ -1,564 +1,20 @@
 
-<img width="800px" src="www/src/collage-top.png"/>
-
-# Chatmail relays for end-to-end encrypted e-mail
+# Chatmail relays for end-to-end encrypted email
 
 Chatmail relay servers are interoperable Mail Transport Agents (MTAs) designed for: 
 
-- **Convenience:** Low friction instant onboarding
+-  **Zero State:** no private data or metadata collected, messages are auto-deleted, low disk usage
 
-- **Privacy:** No name, phone numbers, email required or collected 
+-  **Instant/Realtime:** sub-second message delivery, realtime P2P
+   streaming, privacy-preserving Push Notifications for Apple, Google, and Huawei;
 
-- **End-to-End Encryption enforced**: only OpenPGP messages with metadata minimization allowed 
+-  **Security Enforcement**: only strict TLS, DKIM and OpenPGP with minimized metadata accepted
 
-- **Instant:** Privacy-preserving Push Notifications for Apple, Google, and Huawei
+-  **Reliable Federation and Decentralization:** No spam or IP reputation checks, federating
+   depends on established IETF standards and protocols.
 
-- **Speed:** Message delivery in half a second, with optional P2P realtime connections 
+This repository contains everything needed to setup a ready-to-use chatmail relay on an ssh-reachable host. 
+For getting started and more information please refer to the web version of this repositories' documentation at
 
-- **Transport Security:** Strict TLS and DKIM enforced 
+[https://chatmail.at/doc/relay](https://chatmail.at/doc/relay)
 
-- **Reliability:** No spam or IP reputation checks; rate-limits are suitable for realtime chats
-
-- **Efficiency:** Messages are only stored for transit and removed automatically
-
-This repository contains everything needed to setup a ready-to-use chatmail relay
-comprised of a minimal setup of the battle-tested 
-[Postfix SMTP](https://www.postfix.org) and [Dovecot IMAP](https://www.dovecot.org) MTAs/MDAs.
-
-The automated setup is designed and optimized for providing chatmail addresses
-for immediate permission-free onboarding through chat apps and bots.
-Chatmail addresses are automatically created at first login,
-after which the initially specified password is required
-for sending and receiving messages through them.
-
-Please see [this list of known apps and client projects](https://chatmail.at/clients.html) 
-and [this list of known public 3rd party chatmail relay servers](https://chatmail.at/relays).
-
-
-## Minimal requirements, Prerequisites 
-
-You will need the following: 
-
-- Control over a domain through a DNS provider of your choice.
-
-- A Debian 12 server with reachable SMTP/SUBMISSIONS/IMAPS/HTTPS ports.
-  IPv6 is encouraged if available.
-  Chatmail relay servers only require 1GB RAM, one CPU, and perhaps 10GB storage for a
-  few thousand active chatmail addresses.
-
-- Key-based SSH authentication to the root user.
-  You must add a passphrase-protected private key to your local ssh-agent
-  because you can't type in your passphrase during deployment.
-  (An ed25519 private key is required due to an [upstream bug in paramiko](https://github.com/paramiko/paramiko/issues/2191))
-
-
-## Getting started 
-
-We use `chat.example.org` as the chatmail domain in the following steps.
-Please substitute it with your own domain. 
-
-1. Setup the initial DNS records.
-   The following is an example in the familiar BIND zone file format with
-   a TTL of 1 hour (3600 seconds).
-   Please substitute your domain and IP addresses.
-
-   ```
-    chat.example.com. 3600 IN A 198.51.100.5
-    chat.example.com. 3600 IN AAAA 2001:db8::5
-    www.chat.example.com. 3600 IN CNAME chat.example.com.
-    mta-sts.chat.example.com. 3600 IN CNAME chat.example.com.
-   ```
-
-2. On your local PC, clone the repository and bootstrap the Python virtualenv.
-
-   ```
-    git clone https://github.com/chatmail/relay
-    cd relay
-    scripts/initenv.sh
-   ```
-
-3. On your local PC, create chatmail configuration file `chatmail.ini`:
-
-   ```
-    scripts/cmdeploy init chat.example.org  # <-- use your domain 
-   ```
-
-4. Verify that SSH root login to your remote server works:
-
-   ```
-    ssh root@chat.example.org  # <-- use your domain 
-   ```
-
-5. From your local PC, deploy the remote chatmail relay server:
-
-   ```
-    scripts/cmdeploy run
-   ```
-   This script will also check that you have all necessary DNS records.
-   If DNS records are missing, it will recommend
-   which you should configure at your DNS provider
-   (it can take some time until they are public).
-
-### Other helpful commands
-
-To check the status of your remotely running chatmail service:
-
-```
-scripts/cmdeploy status
-```
-
-To display and check all recommended DNS records:
-
-```
-scripts/cmdeploy dns
-```
-
-To test whether your chatmail service is working correctly:
-
-```
-scripts/cmdeploy test
-```
-
-To measure the performance of your chatmail service:
-
-```
-scripts/cmdeploy bench
-```
-
-## Overview of this repository
-
-This repository has four directories:
-
-- [cmdeploy](https://github.com/chatmail/relay/tree/main/cmdeploy)
-  is a collection of configuration files
-  and a [pyinfra](https://pyinfra.com)-based deployment script.
-
-- [chatmaild](https://github.com/chatmail/relay/tree/main/chatmaild)
-  is a Python package containing several small services
-  which handle authentication,
-  trigger push notifications on new messages,
-  ensure that outbound mails are encrypted,
-  delete inactive users,
-  and some other minor things.
-  chatmaild can also be installed as a stand-alone Python package.
-
-- [www](https://github.com/chatmail/relay/tree/main/www)
-  contains the html, css, and markdown files
-  which make up a chatmail relay's web page.
-  Edit them before deploying to make your chatmail relay stand out.
-
-- [scripts](https://github.com/chatmail/relay/tree/main/scripts)
-  offers two convenience tools for beginners;
-  `initenv.sh` installs the necessary dependencies to a local virtual environment,
-  and the `scripts/cmdeploy` script enables you
-  to run the `cmdeploy` command line tool in the local virtual environment.
-
-### cmdeploy
-
-The `cmdeploy/src/cmdeploy/cmdeploy.py` command line tool
-helps with setting up and managing the chatmail service.
-`cmdeploy init` creates the `chatmail.ini` config file.
-`cmdeploy run` uses a [pyinfra](https://pyinfra.com/)-based [`script`](cmdeploy/src/cmdeploy/__init__.py)
-to automatically install or upgrade all chatmail components on a relay,
-according to the `chatmail.ini` config.
-
-The components of chatmail are:
-
-- [Postfix SMTP MTA](https://www.postfix.org) accepts and relays messages
-  (both from your users and from the wider e-mail MTA network)
-
-- [Dovecot IMAP MDA](https://www.dovecot.org) stores messages for your users until they download them
-
-- [Nginx](https://nginx.org/) shows the web page with your privacy policy and additional information
-
-- [acmetool](https://hlandau.github.io/acmetool/) manages TLS certificates for Dovecot, Postfix, and Nginx
-
-- [OpenDKIM](http://www.opendkim.org/) for signing messages with DKIM and rejecting inbound messages without DKIM
-
-- [mtail](https://google.github.io/mtail/) for collecting anonymized metrics in case you have monitoring
-
-- [Iroh relay](https://www.iroh.computer/docs/concepts/relay) 
-  which helps client devices to establish Peer-to-Peer connections 
-
-- [TURN](https://github.com/chatmail/chatmail-turn)
-  to enable relay users to start webRTC calls
-  even if a p2p connection can't be established
-
-- and the chatmaild services, explained in the next section:
-
-### chatmaild
-
-`chatmaild` implements various systemd-controlled services  
-that integrate with Dovecot and Postfix to achieve instant-onboarding and 
-only relaying OpenPGP end-to-end messages encrypted messages. 
-A short overview of `chatmaild` services: 
-
-- [`doveauth`](https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/doveauth.py) 
-  implements create-on-login address semantics and is used 
-  by Dovecot during IMAP login and by Postfix during SMTP/SUBMISSION login
-  which in turn uses [Dovecot SASL](https://doc.dovecot.org/configuration_manual/authentication/dict/#complete-example-for-authenticating-via-a-unix-socket)
-  to authenticate logins. 
-
-- [`filtermail`](https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/filtermail.py) 
-  prevents unencrypted email from leaving or entering the chatmail service
-  and is integrated into Postfix's outbound and inbound mail pipelines.
-
-- [`chatmail-metadata`](https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/metadata.py) is contacted by a
-  [Dovecot lua script](https://github.com/chatmail/relay/blob/main/cmdeploy/src/cmdeploy/dovecot/push_notification.lua)
-  to store user-specific relay-side config.
-  On new messages,
-  it [passes the user's push notification token](https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/notifier.py)
-  to [notifications.delta.chat](https://delta.chat/help#instant-delivery)
-  so the push notifications on the user's phone can be triggered
-  by Apple/Google/Huawei.
-
-- [`delete_inactive_users`](https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/delete_inactive_users.py)
-  deletes users if they have not logged in for a very long time.
-  The timeframe can be configured in `chatmail.ini`.
-
-- [`lastlogin`](https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/lastlogin.py)
-  is contacted by Dovecot when a user logs in
-  and stores the date of the login.
-
-- [`echobot`](https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/echo.py)
-  is a small bot for test purposes.
-  It simply echoes back messages from users.
-
-- [`chatmail-metrics`](https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/metrics.py)
-  collects some metrics and displays them at `https://example.org/metrics`.
-
-### Home page and getting started for users
-
-`cmdeploy run` also creates default static web pages and deploys them
-to a Nginx web server with:
-
-- a default `index.html` along with a QR code that users can click to
-  create an address on your chatmail relay 
-
-- a default `info.html` that is linked from the home page
-
-- a default `policy.html` that is linked from the home page
-
-All `.html` files are generated
-by the according markdown `.md` file in the `www/src` directory.
-
-
-### Refining the web pages
-
-```
-scripts/cmdeploy webdev
-```
-
-This starts a local live development cycle for chatmail web pages:
-
-- uses the `www/src/page-layout.html` file for producing static
-  HTML pages from `www/src/*.md` files
-
-- continously builds the web presence reading files from `www/src` directory
-  and generating HTML files and copying assets to the `www/build` directory.
-
-- Starts a browser window automatically where you can "refresh" as needed.
-
-#### Custom web pages
-
-You can skip uploading a web page
-by setting `www_folder=disabled` in `chatmail.ini`.
-
-If you want to manage your web pages outside this git repository,
-you can set `www_folder` in `chatmail.ini` to a custom directory on your computer.
-`cmdeploy run` will upload it as the server's home page,
-and if it contains a `src/index.md` file,
-will build it with hugo.
-
-
-## Mailbox directory layout
-
-Fresh chatmail addresses have a mailbox directory that contains: 
-
-- a `password` file with the salted password required for authenticating
-  whether a login may use the address to send/receive messages. 
-  If you modify the password file manually, you effectively block the user. 
-
-- `enforceE2EEincoming` is a default-created file with each address. 
-  If present the file indicates that this chatmail address rejects incoming cleartext messages.
-  If absent the address accepts incoming cleartext messages. 
-
-- `dovecot*`, `cur`, `new` and `tmp` represent IMAP/mailbox state. 
-  If the address is only used by one device, the Maildir directories
-  will typically be empty unless the user of that address hasn't been online 
-  for a while. 
-
-
-## Emergency Commands to disable automatic address creation
-
-If you need to stop address creation,
-e.g. because some script is wildly creating addresses, 
-login with ssh and run:
-
-```
-    touch /etc/chatmail-nocreate
-```
-
-Chatmail address creation will be denied while this file is present.
-
-### Ports
-
-[Postfix](http://www.postfix.org/) listens on ports 25 (SMTP) and 587 (SUBMISSION) and 465 (SUBMISSIONS).
-[Dovecot](https://www.dovecot.org/) listens on ports 143 (IMAP) and 993 (IMAPS).
-[Nginx](https://www.nginx.com/) listens on port 8443 (HTTPS-ALT) and 443 (HTTPS).
-Port 443 multiplexes HTTPS, IMAP and SMTP using ALPN to redirect connections to ports 8443, 465 or 993.
-[acmetool](https://hlandau.github.io/acmetool/) listens on port 80 (HTTP).
-[chatmail-turn](https://github.com/chatmail/chatmail-turn) listens on UDP port 3478 (STUN/TURN),
-and temporarily opens UDP ports when users request them. UDP port range is not restricted, any free port may be allocated.
-
-chatmail-core based apps will, however, discover all ports and configurations
-automatically by reading the [autoconfig XML file](https://www.ietf.org/archive/id/draft-bucksch-autoconfig-00.html) from the chatmail relay server.
-
-## Email authentication
-
-Chatmail relays enforce [DKIM](https://www.rfc-editor.org/rfc/rfc6376)
-to authenticate incoming emails.
-Incoming emails must have a valid DKIM signature with
-Signing Domain Identifier (SDID, `d=` parameter in the DKIM-Signature header)
-equal to the `From:` header domain.
-This property is checked by OpenDKIM screen policy script
-before validating the signatures.
-This correpsonds to strict [DMARC](https://www.rfc-editor.org/rfc/rfc7489) alignment (`adkim=s`),
-but chatmail does not rely on DMARC and does not consult the sender policy published in DMARC records.
-Other legacy authentication mechanisms such as [iprev](https://www.rfc-editor.org/rfc/rfc8601#section-2.7.3)
-and [SPF](https://www.rfc-editor.org/rfc/rfc7208) are also not taken into account.
-If there is no valid DKIM signature on the incoming email,
-the sender receives a "5.7.1 No valid DKIM signature found" error.
-
-Outgoing emails must be sent over authenticated connection
-with envelope MAIL FROM (return path) corresponding to the login.
-This is ensured by Postfix which maps login username
-to MAIL FROM with
-[`smtpd_sender_login_maps`](https://www.postfix.org/postconf.5.html#smtpd_sender_login_maps)
-and rejects incorrectly authenticated emails with [`reject_sender_login_mismatch`](reject_sender_login_mismatch) policy.
-`From:` header must correspond to envelope MAIL FROM,
-this is ensured by `filtermail` proxy.
-
-## TLS requirements
-
-Postfix is configured to require valid TLS
-by setting [`smtp_tls_security_level`](https://www.postfix.org/postconf.5.html#smtp_tls_security_level) to `verify`.
-If emails don't arrive at your chatmail relay server, 
-the problem is likely that your relay does not have a valid TLS certificate.
-
-You can test it by resolving `MX` records of your relay domain
-and then connecting to MX relays (e.g `mx.example.org`) with
-`openssl s_client -connect mx.example.org:25 -verify_hostname mx.example.org -verify_return_error -starttls smtp`
-from the host that has open port 25 to verify that certificate is valid.
-
-When providing a TLS certificate to your chatmail relay server, 
-make sure to provide the full certificate chain
-and not just the last certificate.
-
-If you are running an Exim server and don't see incoming connections
-from a chatmail relay server in the logs,
-make sure `smtp_no_mail` log item is enabled in the config
-with `log_selector = +smtp_no_mail`.
-By default Exim does not log sessions that are closed
-before sending the `MAIL` command.
-This happens if certificate is not recognized as valid by Postfix,
-so you might think that connection is not established
-while actually it is a problem with your TLS certificate.
-
-## Migrating a chatmail relay to a new host
-
-If you want to migrate chatmail relay from an old machine
-to a new machine,
-you can use these steps.
-They were tested with a Linux laptop;
-you might need to adjust some of the steps to your environment.
-
-Let's assume that your `mail_domain` is `mail.example.org`,
-all involved machines run Debian 12,
-your old site's IP address is `13.37.13.37`,
-and your new site's IP address is `13.12.23.42`.
-
-Note, you should lower the TTLs of your DNS records to a value
-such as 300 (5 minutes) so the migration happens as smoothly as possible.
-
-During the guide you might get a warning about changed SSH Host keys;
-in this case, just run `ssh-keygen -R "mail.example.org"` as recommended.
-
-1. First, disable mail services on the old site. 
-
-   ```
-    cmdeploy run --disable-mail --ssh-host 13.37.13.37
-   ```
-
-   Now your users will notice the migration
-   and will not be able to send or receive messages
-   until the migration is completed.
-
-2. Now we want to copy `/home/vmail`, `/var/lib/acme`, `/etc/dkimkeys`, `/run/echobot`, and `/var/spool/postfix` to the new site. 
-   Login to the old site while forwarding your SSH agent 
-   so you can copy directly from the old to the new site with your SSH key:
-   ```
-    ssh -A root@13.37.13.37
-    tar c - /home/vmail/mail /var/lib/acme /etc/dkimkeys /run/echobot /var/spool/postfix | ssh root@13.12.23.42 "tar x -C /"
-   ```
-
-   This transfers all addresses, the TLS certificate, DKIM keys (so DKIM DNS record remains valid), and the echobot's password so it continues to function.
-   It also preserves the Postfix mail spool so any messages pending delivery will still be delivered.
-
-3. Install chatmail on the new machine:
-
-   ```
-    cmdeploy run --disable-mail --ssh-host 13.12.23.42
-   ```
-   Postfix and Dovecot are disabled for now; we will enable them later. 
-   We first need to make the new site fully operational. 
-
-3. On the new site, run the following to ensure the ownership is correct in case UIDs/GIDs changed:
-
-   ```
-    chown root: -R /var/lib/acme
-    chown opendkim: -R /etc/dkimkeys
-    chown vmail: -R /home/vmail/mail
-    chown echobot: -R /run/echobot
-   ```
-
-4. Now, update DNS entries. 
-
-   If other MTAs try to deliver messages to your chatmail domain they may fail intermittently,
-   as DNS catches up with the new site settings 
-   but normally will retry delivering messages
-   for at least a week, so messages will not be lost.
-
-5. Finally, you can execute `cmdeploy run --ssh-host 13.12.23.42` to turn on chatmail on the new relay.
-   Your users will be able to use the chatmail relay as soon as the DNS changes have propagated.
-   Voilà!
-
-## Setting up a reverse proxy
-
-A chatmail relay MTA does not track or depend on the client IP address
-for its operation, so it can be run behind a reverse proxy.
-This will not even affect incoming mail authentication
-as DKIM only checks the cryptographic signature
-of the message and does not use the IP address as the input.
-
-For example, you may want to self-host your chatmail relay
-and only use hosted VPS to provide a public IP address
-for client connections and incoming mail.
-You can connect chatmail relay to VPS
-using a tunnel protocol
-such as [WireGuard](https://www.wireguard.com/)
-and setup a reverse proxy on a VPS
-to forward connections to the chatmail relay
-over the tunnel.
-You can also setup multiple reverse proxies
-for your chatmail relay in different networks
-to ensure your relay is reachable even when
-one of the IPs becomes inaccessible due to
-hosting or routing problems.
-
-Note that your chatmail relay still needs
-to be able to make outgoing connections on port 25
-to send messages outside.
-
-To setup a reverse proxy
-(or rather Destination NAT, DNAT)
-for your chatmail relay,
-put the following configuration in `/etc/nftables.conf`:
-```
-#!/usr/sbin/nft -f
-
-flush ruleset
-
-define wan = eth0
-
-# Which ports to proxy.
-#
-# Note that SSH is not proxied
-# so it is possible to log into the proxy server 
-# and not the original one.
-define ports = { smtp, http, https, imap, imaps, submission, submissions }
-
-# The host we want to proxy to.
-define ipv4_address = AAA.BBB.CCC.DDD
-define ipv6_address = [XXX::1]
-
-table ip nat {
-        chain prerouting {
-                type nat hook prerouting priority dstnat; policy accept;
-                iif $wan tcp dport $ports dnat to $ipv4_address
-        }
-
-        chain postrouting {
-                type nat hook postrouting priority 0;
-
-                oifname $wan masquerade
-        }
-}
-
-table ip6 nat {
-        chain prerouting {
-                type nat hook prerouting priority dstnat; policy accept;
-                iif $wan tcp dport $ports dnat to $ipv6_address
-        }
-
-        chain postrouting {
-                type nat hook postrouting priority 0;
-
-                oifname $wan masquerade
-        }
-}
-
-table inet filter {
-        chain input {
-                type filter hook input priority filter; policy drop;
-
-                # Accept ICMP.
-                # It is especially important to accept ICMPv6 ND messages,
-                # otherwise IPv6 connectivity breaks.
-                icmp type { echo-request } accept
-                icmpv6 type { echo-request, nd-neighbor-solicit, nd-router-advert, nd-neighbor-advert } accept
-
-                # Allow incoming SSH connections.
-                tcp dport { ssh } accept
-
-                ct state established accept
-        }
-        chain forward {
-                type filter hook forward priority filter; policy drop;
-
-                ct state established accept
-                ip daddr $ipv4_address counter accept
-                ip6 daddr $ipv6_address counter accept
-        }
-        chain output {
-                type filter hook output priority filter;
-        }
-}
-```
-
-Run `systemctl enable nftables.service`
-to ensure configuration is reloaded when the proxy relay reboots.
-
-Uncomment in `/etc/sysctl.conf` the following two lines:
-
-```
-net.ipv4.ip_forward=1
-net.ipv6.conf.all.forwarding=1
-```
-
-Then reboot the relay or do `sysctl -p` and `nft -f /etc/nftables.conf`.
-
-Once proxy relay is set up,
-you can add its IP address to the DNS.
-
-## Neighbors and Acquaintances
-
-Here are some related projects that you may be interested in:
-
-- [Mox](https://github.com/mjl-/mox): A Golang email server.  [Work is in
-  progress](https://github.com/mjl-/mox/issues/251) to modify it to support all
-  of the features and configuration settings required to operate as a chatmail
-  relay.
-- [Maddy-Chatmail](https://github.com/sadraiiali/maddy_chatmail): a plugin for the
-  [Maddy email server](https://maddy.email/) which aims to implement the
-  chatmail relay features and configuration options.

chatmaild/src/chatmaild/ini/chatmail.ini.f

@@ -43,7 +43,7 @@ passthrough_senders =
 
 # list of e-mail recipients for which to accept outbound un-encrypted mails
 # (space-separated, item may start with "@" to whitelist whole recipient domains)
-passthrough_recipients = xstore@testrun.org echo@{mail_domain}
+passthrough_recipients = echo@{mail_domain}
 
 # path to www directory - documented here: https://github.com/chatmail/relay/#custom-web-pages
 #www_folder = www

chatmaild/src/chatmaild/ini/override-testrun.ini

@@ -1,7 +1,7 @@
 
 [privacy]
 
-passthrough_recipients = privacy@testrun.org xstore@testrun.org echo@{mail_domain}
+passthrough_recipients = privacy@testrun.org echo@{mail_domain}
 
 privacy_postal =
     Merlinux GmbH, Represented by the managing director H. Krekel,

cmdeploy/src/cmdeploy/acmetool/__init__.py

@@ -2,66 +2,121 @@ import importlib.resources
 
 from pyinfra.operations import apt, files, server, systemd
 
+from ..deployer import Deployer
 
-def deploy_acmetool(email="", domains=[]):
-    """Deploy acmetool."""
-    apt.packages(
-        name="Install acmetool",
-        packages=["acmetool"],
-    )
 
-    files.put(
-        src=importlib.resources.files(__package__).joinpath("acmetool.cron").open("rb"),
-        dest="/etc/cron.d/acmetool",
-        user="root",
-        group="root",
-        mode="644",
-    )
+class AcmetoolDeployer(Deployer):
+    def __init__(self, email, domains):
+        self.domains = domains
+        self.email = email
+        self.need_restart_redirector = False
+        self.need_restart_reconcile_service = False
+        self.need_restart_reconcile_timer = False
 
-    files.put(
-        src=importlib.resources.files(__package__).joinpath("acmetool.hook").open("rb"),
-        dest="/usr/lib/acme/hooks/nginx",
-        user="root",
-        group="root",
-        mode="744",
-    )
+    def install(self):
+        apt.packages(
+            name="Install acmetool",
+            packages=["acmetool"],
+        )
 
-    files.template(
-        src=importlib.resources.files(__package__).joinpath("response-file.yaml.j2"),
-        dest="/var/lib/acme/conf/responses",
-        user="root",
-        group="root",
-        mode="644",
-        email=email,
-    )
+        files.file(
+            name="Remove old acmetool cronjob, it is replaced with systemd timer.",
+            path="/etc/cron.d/acmetool",
+            present=False,
+        )
 
-    files.template(
-        src=importlib.resources.files(__package__).joinpath("target.yaml.j2"),
-        dest="/var/lib/acme/conf/target",
-        user="root",
-        group="root",
-        mode="644",
-    )
+        files.put(
+            name="Install acmetool hook.",
+            src=importlib.resources.files(__package__).joinpath("acmetool.hook").open("rb"),
+            dest="/etc/acme/hooks/nginx",
+            user="root",
+            group="root",
+            mode="755",
+        )
+        files.file(
+            name="Remove acmetool hook from the wrong location where it was previously installed.",
+            path="/usr/lib/acme/hooks/nginx",
+            present=False,
+        )
 
-    service_file = files.put(
-        src=importlib.resources.files(__package__).joinpath(
-            "acmetool-redirector.service"
-        ),
-        dest="/etc/systemd/system/acmetool-redirector.service",
-        user="root",
-        group="root",
-        mode="644",
-    )
+    def configure(self):
+        files.template(
+            src=importlib.resources.files(__package__).joinpath("response-file.yaml.j2"),
+            dest="/var/lib/acme/conf/responses",
+            user="root",
+            group="root",
+            mode="644",
+            email=self.email,
+        )
 
-    systemd.service(
-        name="Setup acmetool-redirector service",
-        service="acmetool-redirector.service",
-        running=True,
-        enabled=True,
-        restarted=service_file.changed,
-    )
+        files.template(
+            src=importlib.resources.files(__package__).joinpath("target.yaml.j2"),
+            dest="/var/lib/acme/conf/target",
+            user="root",
+            group="root",
+            mode="644",
+        )
 
-    server.shell(
-        name=f"Request certificate for: {', '.join(domains)}",
-        commands=[f"acmetool want --xlog.severity=debug {' '.join(domains)}"],
-    )
+        service_file = files.put(
+            src=importlib.resources.files(__package__).joinpath(
+                "acmetool-redirector.service"
+            ),
+            dest="/etc/systemd/system/acmetool-redirector.service",
+            user="root",
+            group="root",
+            mode="644",
+        )
+        self.need_restart_redirector = service_file.changed
+
+        reconcile_service_file = files.put(
+            src=importlib.resources.files(__package__).joinpath(
+                "acmetool-reconcile.service"
+            ),
+            dest="/etc/systemd/system/acmetool-reconcile.service",
+            user="root",
+            group="root",
+            mode="644",
+        )
+        self.need_restart_reconcile_service = reconcile_service_file.changed
+
+        reconcile_timer_file = files.put(
+            src=importlib.resources.files(__package__).joinpath("acmetool-reconcile.timer"),
+            dest="/etc/systemd/system/acmetool-reconcile.timer",
+            user="root",
+            group="root",
+            mode="644",
+        )
+        self.need_restart_reconcile_timer = reconcile_timer_file.changed
+
+    def activate(self):
+        systemd.service(
+            name="Setup acmetool-redirector service",
+            service="acmetool-redirector.service",
+            running=True,
+            enabled=True,
+            restarted=self.need_restart_redirector,
+        )
+        self.need_restart_redirector = False
+
+        systemd.service(
+            name="Setup acmetool-reconcile service",
+            service="acmetool-reconcile.service",
+            running=False,
+            enabled=False,
+            daemon_reload=self.need_restart_reconcile_service,
+        )
+        self.need_restart_reconcile_service = False
+
+        systemd.service(
+            name="Setup acmetool-reconcile timer",
+            service="acmetool-reconcile.timer",
+            running=True,
+            enabled=True,
+            daemon_reload=self.need_restart_reconcile_timer,
+        )
+        self.need_restart_reconcile_timer = False
+
+        server.shell(
+            name=f"Request certificate for: {', '.join(self.domains)}",
+            commands=[f"acmetool want --xlog.severity=debug {' '.join(self.domains)}"],
+        )

cmdeploy/src/cmdeploy/acmetool/acmetool-reconcile.service

@@ -0,0 +1,8 @@
+[Unit]
+Description=Renew TLS certificates with acmetool
+After=network.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/acmetool --batch reconcile
+

cmdeploy/src/cmdeploy/acmetool/acmetool-reconcile.timer

@@ -0,0 +1,8 @@
+[Unit]
+Description=Renew TLS certificates with acmetool
+
+[Timer]
+OnCalendar=*-*-* 16:20:00
+
+[Install]
+WantedBy=timers.target

cmdeploy/src/cmdeploy/acmetool/acmetool.cron

@@ -1,4 +0,0 @@
-SHELL=/bin/sh
-PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin
-MAILTO=root
-20 16 * * * root /usr/bin/acmetool --batch reconcile && systemctl reload dovecot && systemctl reload postfix && systemctl reload nginx

cmdeploy/src/cmdeploy/cmdeploy.py

@@ -171,10 +171,15 @@ def dns_cmd(args, out):
     return retcode
 
 
+def status_cmd_options(parser):
+    add_ssh_host_option(parser)
+
+
 def status_cmd(args, out):
     """Display status for online chatmail instance."""
 
-    sshexec = args.get_sshexec()
+    ssh_host = args.ssh_host if args.ssh_host else args.config.mail_domain
+    sshexec = get_sshexec(ssh_host, verbose=args.verbose)
 
     out.green(f"chatmail domain: {args.config.mail_domain}")
     if args.config.privacy_mail:

cmdeploy/src/cmdeploy/deployer.py

@@ -0,0 +1,57 @@
+import os
+
+from pyinfra.operations import server
+
+
+class Deployment:
+    def install(self, deployer):
+        # optional 'required_users' contains a list of (user, group, secondary-group-list) tuples.
+        # If the group is None, no group is created corresponding to that user.
+        # If the secondary group list is not None, all listed groups are created as well.
+        required_users = getattr(deployer, "required_users", [])
+        for user, group, groups in required_users:
+            if group is not None:
+                server.group(
+                    name="Create {} group".format(group), group=group, system=True
+                )
+            if groups is not None:
+                for group2 in groups:
+                    server.group(
+                        name="Create {} group".format(group2), group=group2, system=True
+                    )
+            server.user(
+                name="Create {} user".format(user),
+                user=user,
+                group=group,
+                groups=groups,
+                system=True,
+            )
+
+        deployer.install()
+
+    def configure(self, deployer):
+        deployer.configure()
+
+    def activate(self, deployer):
+        deployer.activate()
+
+    def perform_stages(self, deployers):
+        default_stages = "install,configure,activate"
+        stages = os.getenv("CMDEPLOY_STAGES", default_stages).split(",")
+
+        for stage in stages:
+            for deployer in deployers:
+                getattr(self, stage)(deployer)
+
+
+class Deployer:
+    need_restart = False
+
+    def install(self):
+        pass
+
+    def configure(self):
+        pass
+
+    def activate(self):
+        pass

cmdeploy/src/cmdeploy/policy-rc.d

@@ -0,0 +1,3 @@
+#!/bin/sh
+echo "All runlevel operations denied by policy" >&2
+exit 101

cmdeploy/src/cmdeploy/remote/rdns.py

@@ -73,9 +73,7 @@ def query_dns(typ, domain):
 
     # Query authoritative nameserver directly to bypass DNS cache.
     res = shell(f"dig @{ns} -r -q {domain} -t {typ} +short", print=log_progress)
-    if res:
-        return res.split("\n")[0]
-    return ""
+    return next((line for line in res.split("\n") if not line.startswith(';')), '')
 
 
 def check_zonefile(zonefile, verbose=True):

cmdeploy/src/cmdeploy/tests/online/benchmark.py

@@ -37,7 +37,7 @@ class TestDC:
 
     def test_ping_pong(self, benchmark, cmfactory):
         ac1, ac2 = cmfactory.get_online_accounts(2)
-        chat = cmfactory.get_protected_chat(ac1, ac2)
+        chat = cmfactory.get_accepted_chat(ac1, ac2)
 
         def dc_ping_pong():
             chat.send_text("ping")
@@ -49,7 +49,7 @@ class TestDC:
 
     def test_send_10_receive_10(self, benchmark, cmfactory, lp):
         ac1, ac2 = cmfactory.get_online_accounts(2)
-        chat = cmfactory.get_protected_chat(ac1, ac2)
+        chat = cmfactory.get_accepted_chat(ac1, ac2)
 
         def dc_send_10_receive_10():
             for i in range(10):

cmdeploy/src/cmdeploy/tests/online/test_1_basic.py

@@ -1,4 +1,5 @@
 import datetime
+import os
 import smtplib
 import socket
 import subprocess
@@ -7,6 +8,7 @@ import time
 import pytest
 
 from cmdeploy import remote
+from cmdeploy.cmdeploy import main
 from cmdeploy.sshexec import SSHExec
 
 
@@ -68,6 +70,47 @@ class TestSSHExecutor:
         assert (now - since_date).total_seconds() < 60 * 60 * 51
 
 
+def test_status_cmd(chatmail_config, capsys, request):
+    os.chdir(request.config.invocation_params.dir)
+    assert main(["status"]) == 0
+    status_out = capsys.readouterr()
+    print(status_out.out)
+
+    services = [
+        "acmetool-redirector",
+        "chatmail-metadata",
+        "doveauth",
+        "dovecot",
+        "echobot",
+        "fcgiwrap",
+        "filtermail-incoming",
+        "filtermail",
+        "lastlogin",
+        "nginx",
+        "opendkim",
+        "postfix@-",
+        "systemd-journald",
+        "turnserver",
+        "unbound",
+    ]
+    not_running = []
+    for service in services:
+        active = False
+        for line in status_out:
+            if service in line:
+                active = True
+                if not "loaded" in line:
+                    active = False
+                if not "active" in line:
+                    active = False
+                if not "running" in line:
+                    active = False
+                break
+        if not active:
+            not_running.append(service)
+    assert not_running == []
+
+
 def test_timezone_env(remote):
     for line in remote.iter_output("env"):
         print(line)

cmdeploy/src/cmdeploy/tests/online/test_2_deltachat.py

@@ -56,7 +56,7 @@ class TestEndToEndDeltaChat:
         """Test that a DC account can send a message to a second DC account
         on the same chat-mail instance."""
         ac1, ac2 = cmfactory.get_online_accounts(2)
-        chat = cmfactory.get_protected_chat(ac1, ac2)
+        chat = cmfactory.get_accepted_chat(ac1, ac2)
         chat.send_text("message0")
 
         lp.sec("wait for ac2 to receive message")
@@ -70,7 +70,7 @@ class TestEndToEndDeltaChat:
         before quota is exceeded, and thus depends on the speed of the upload.
         """
         ac1, ac2 = cmfactory.get_online_accounts(2)
-        chat = cmfactory.get_protected_chat(ac1, ac2)
+        chat = cmfactory.get_accepted_chat(ac1, ac2)
 
         user = ac2.get_config("configured_addr")
 
@@ -153,7 +153,7 @@ def test_hide_senders_ip_address(cmfactory):
     assert ipaddress.ip_address(public_ip)
 
     user1, user2 = cmfactory.get_online_accounts(2)
-    chat = cmfactory.get_protected_chat(user1, user2)
+    chat = cmfactory.get_accepted_chat(user1, user2)
 
     chat.send_text("testing submission header cleanup")
     user2._evtracker.wait_next_incoming_message()

cmdeploy/src/cmdeploy/tests/test_dns.py

@@ -1,3 +1,5 @@
+from copy import deepcopy
+
 import pytest
 
 from cmdeploy import remote
@@ -8,38 +10,63 @@ from cmdeploy.dns import check_full_zone, check_initial_remote_data
 def mockdns_base(monkeypatch):
     qdict = {}
 
-    def query_dns(typ, domain):
-        try:
-            return qdict[typ][domain]
-        except KeyError:
-            return ""
+    def shell(command, fail_ok=False, print=print):
+        if command.startswith("dig"):
+            if command == "dig":
+                return "."
+            if "SOA" in command:
+                return (
+                    "delta.chat. 21600 IN SOA ns1.first-ns.de. dns.hetzner.com."
+                    " 2025102800 14400 1800 604800 3600"
+                )
+            command_chunks = command.split()
+            domain, typ = command_chunks[4], command_chunks[6]
+            try:
+                return qdict[typ][domain]
+            except KeyError:
+                return ""
+        return remote.rshell.shell(command=command, fail_ok=fail_ok, print=print)
 
-    monkeypatch.setattr(remote.rdns, query_dns.__name__, query_dns)
+    monkeypatch.setattr(remote.rdns, shell.__name__, shell)
     return qdict
 
 
 @pytest.fixture
-def mockdns(mockdns_base):
-    mockdns_base.update(
-        {
-            "A": {"some.domain": "1.1.1.1"},
-            "AAAA": {"some.domain": "fde5:cd7a:9e1c:3240:5a99:936f:cdac:53ae"},
-            "CNAME": {
-                "mta-sts.some.domain": "some.domain.",
-                "www.some.domain": "some.domain.",
-            },
-        }
-    )
+def mockdns_expected():
+    return {
+        "A": {"some.domain": "1.1.1.1"},
+        "AAAA": {"some.domain": "fde5:cd7a:9e1c:3240:5a99:936f:cdac:53ae"},
+        "CNAME": {
+            "mta-sts.some.domain": "some.domain.",
+            "www.some.domain": "some.domain.",
+        },
+    }
+
+
+@pytest.fixture(params=["plain", "with-dns-comments"])
+def mockdns(request, mockdns_base, mockdns_expected):
+    mockdns_base.update(deepcopy(mockdns_expected))
+    match request.param:
+        case "plain":
+            pass
+        case "with-dns-comments":
+            for typ, data in mockdns_base.items():
+                for host, result in data.items():
+                    mockdns_base[typ][host] = (
+                        ";; some unsuccessful attempt result\n"
+                        "; and another with a single semicolon\n"
+                        f"{result}"
+                    )
     return mockdns_base
 
 
 class TestPerformInitialChecks:
-    def test_perform_initial_checks_ok1(self, mockdns):
+    def test_perform_initial_checks_ok1(self, mockdns, mockdns_expected):
         remote_data = remote.rdns.perform_initial_checks("some.domain")
-        assert remote_data["A"] == mockdns["A"]["some.domain"]
-        assert remote_data["AAAA"] == mockdns["AAAA"]["some.domain"]
-        assert remote_data["MTA_STS"] == mockdns["CNAME"]["mta-sts.some.domain"]
-        assert remote_data["WWW"] == mockdns["CNAME"]["www.some.domain"]
+        assert remote_data["A"] == mockdns_expected["A"]["some.domain"]
+        assert remote_data["AAAA"] == mockdns_expected["AAAA"]["some.domain"]
+        assert remote_data["MTA_STS"] == mockdns_expected["CNAME"]["mta-sts.some.domain"]
+        assert remote_data["WWW"] == mockdns_expected["CNAME"]["www.some.domain"]
 
     @pytest.mark.parametrize("drop", ["A", "AAAA"])
     def test_perform_initial_checks_with_one_of_A_AAAA(self, mockdns, drop):

cmdeploy/src/cmdeploy/www.py

@@ -4,6 +4,7 @@ import time
 import traceback
 import webbrowser
 from pathlib import Path
+import re
 
 import markdown
 from chatmaild.config import read_config
@@ -12,6 +13,9 @@ from jinja2 import Template
 from .genqr import gen_qr_png_data
 
 
+_MERGE_CONFLICT_RE = re.compile(r"^<<<<<<<.+^=======.+^>>>>>>>", re.DOTALL | re.MULTILINE)
+
+
 def snapshot_dir_stats(somedir):
     d = {}
     for path in somedir.iterdir():
@@ -116,6 +120,17 @@ def _build_webpages(src_dir, build_dir, config):
     return build_dir
 
 
+def find_merge_conflict(src_dir) -> Path:
+    assert src_dir.exists(), src_dir
+    result = None
+    for path in src_dir.iterdir():
+        if path.suffix in [".css", ".html", ".md"]:
+            if _MERGE_CONFLICT_RE.search(path.read_text()):
+                result = path
+                break
+    return result
+
+
 def main():
     path = importlib.resources.files(__package__)
     reporoot = path.joinpath("../../../").resolve()

doc/Makefile

@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+auto: 
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile auto
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+

doc/README.md

@@ -0,0 +1,17 @@
+
+
+## Building the documentation 
+
+You can use the `make` command and `make html` to build web pages. 
+
+You need a Python environment where the following install was excuted: 
+
+    pip install sphinx-build furo sphinx-autobuild 
+
+To develop/change documentation, you can then do: 
+
+    make auto 
+
+A page will open at https://127.0.0.1:8000/ serving the docs and it will 
+react to changes to source files pretty fast. 
+

doc/source/_static/chatmail.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg" id="svg4" width="145" height="145" version="1.1"><g id="text2" aria-label="@" style="font-size:144px;font-family:Arial" transform="matrix(1.0934997,0,0,1.0934997,-6.7787266,-6.7787281)"><path id="path347" d="m 79.927878,94.422406 c -2.704286,3.120332 -5.741407,5.637394 -9.111364,7.551194 -3.328352,1.87221 -6.677506,2.80831 -10.047463,2.80831 -3.702792,0 -7.301573,-1.08172 -10.796342,-3.24515 -3.49477,-2.163426 -6.344671,-5.491779 -8.549704,-9.985058 -2.163429,-4.493275 -3.245144,-9.423397 -3.245144,-14.790365 0,-6.615099 1.684978,-13.230199 5.054935,-19.845299 3.411561,-6.656705 7.634407,-11.649233 12.66854,-14.977585 5.034133,-3.328352 9.92265,-4.992528 14.665552,-4.992528 3.619583,0 7.072748,0.956901 10.359496,2.870704 3.286748,1.872198 6.115847,4.742902 8.487297,8.612111 l 2.121825,-9.673023 h 11.170784 l -8.986557,41.87483 c -1.248129,5.824616 -1.872194,9.048957 -1.872194,9.673023 0,1.123319 0.416044,2.101022 1.248132,2.93311 0.873692,0.790484 1.913802,1.185726 3.120332,1.185726 2.20503,0 5.096537,-1.268934 8.674517,-3.806803 4.7429,-3.328352 8.4873,-7.780023 11.23319,-13.355013 2.78749,-5.616594 4.18124,-11.399606 4.18124,-17.349035 0,-6.947935 -1.78899,-13.438222 -5.36697,-19.47086 -3.53637,-6.032638 -8.84094,-10.858749 -15.913687,-14.478332 -7.03114,-3.619583 -14.811161,-5.429374 -23.340064,-5.429374 -9.73543,0 -18.638772,2.288242 -26.710026,6.864726 -8.029649,4.534879 -14.27031,11.06677 -18.721981,19.595673 -4.410066,8.487298 -6.615099,17.598662 -6.615099,27.334092 0,10.193078 2.205033,18.971607 6.615099,26.33559 2.290454,3.78888 -7.136335,18.96983 -3.810585,21.73443 3.138096,2.60861 18.971963,-7.14297 23.031819,-5.44631 8.404089,3.53637 17.702673,5.30456 27.895752,5.30456 10.90035,0 20.032515,-1.83059 27.396492,-5.49178 7.36399,-3.66119 12.87657,-8.11286 16.53776,-13.35501 l 9.29559,4 c -2.12183,4.36846 -3.76221,4.82013 -8.92116,9.35501 -5.15895,4.53488 -11.2956,8.11286 -18.40995,10.73393 -7.114346,2.66268 -15.684851,3.99402 -25.711512,3.99402 -9.236177,0 -17.76508,-1.18572 -25.586707,-3.55717 -7.780023,-2.37145 -29.296198,9.26152 -34.78798,4.47701 -5.49178,-4.7429 5.248856,-25.42482 2.461361,-31.62388 -3.49477,-7.863231 -5.242155,-16.350531 -5.242155,-25.461894 0,-10.151474 2.08022,-19.824498 6.240661,-29.019071 5.075736,-11.274793 12.273297,-19.907706 21.592683,-25.898739 9.360991,-5.991034 20.69819,-8.986551 34.011599,-8.986551 10.317891,0 19.574873,2.121824 27.77093,6.365473 8.23767,4.202045 14.72796,10.484309 19.47086,18.846794 4.03563,7.197561 6.05344,15.019189 6.05344,23.464883 0,12.065277 -4.24365,22.77841 -12.73094,32.1394 -7.572,8.404095 -15.85128,12.606135 -24.837827,12.606135 -2.870704,0 -5.200551,-0.43684 -6.98954,-1.31053 -1.747385,-0.8737 -3.037121,-2.12183 -3.869209,-3.744402 -0.540857,-1.040114 -0.936099,-2.829105 -1.185726,-5.366972 z M 49.723082,77.510217 c 0,5.699803 1.352143,10.130671 4.05643,13.292606 2.704286,3.161935 5.803814,4.742902 9.298583,4.742902 2.329847,0 4.784506,-0.686473 7.363979,-2.059418 2.579473,-1.41455 5.034133,-3.49477 7.363979,-6.240661 2.371451,-2.74589 4.306056,-6.219857 5.803815,-10.421902 1.497759,-4.243649 2.246638,-8.487298 2.246638,-12.730947 0,-5.658198 -1.41455,-10.047462 -4.243649,-13.167793 -2.787495,-3.12033 -6.199056,-4.680495 -10.234683,-4.680495 -2.662682,0 -5.179749,0.686473 -7.5512,2.059418 -2.329846,1.331341 -4.597286,3.494769 -6.802319,6.490286 -2.205033,2.995517 -3.97322,6.635903 -5.304561,10.921156 -1.331341,4.285253 -1.997012,8.216869 -1.997012,11.794848 z" style="stroke-width:.887561"/></g></svg>

doc/source/_static/custom.css

@@ -0,0 +1,21 @@
+/* Tweak how the sidebar logo is presented */
+.sidebar-logo {
+  width: 70%;
+}
+.sidebar-brand {
+  padding: 0;
+}
+
+/* The landing pages' sidebar-in-content highlights */
+#features ul {
+  padding-left: 1rem;
+  list-style: none;
+}
+#features ul li {
+  margin-bottom: 0;
+}
+@media (min-width: 46em) {
+  #features {
+    width: 50%;
+  }
+}

doc/source/conf.py

@@ -0,0 +1,41 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'chatmail relay documentation'
+copyright = '2025, chatmail collective'
+author = 'chatmail collective'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    #'sphinx.ext.autodoc',
+    #'sphinx.ext.viewdoc',
+    'sphinxcontrib.mermaid',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']
+html_css_files = [
+    "custom.css",
+]
+
+html_title = "chatmail relay documentation"
+#html_short_title = f"chatmail-{release}"
+
+html_logo = "_static/chatmail.svg"
+
+

doc/source/faq.rst

@@ -0,0 +1,61 @@
+
+
+Frequently asked questions
+===========================
+
+What is the difference between chatmail relays and classic email servers?
+--------------------------------------------------------------------------
+
+A chatmail relay is a minimal Mail Transport Agent (MTA) setup that
+goes beyond what classic email servers offer:
+
+-  **Zero State:** no private data or metadata collected, messages are auto-deleted, low disk usage
+
+-  **Instant/Realtime:** sub-second message delivery, realtime P2P
+   streaming, privacy-preserving Push Notifications for Apple, Google, and `Ubuntu Touch <https://docs.ubports.com/en/latest/appdev/guides/pushnotifications.html>`_;
+
+-  **Security Enforcement**: only strict TLS, DKIM and OpenPGP with minimized metadata accepted
+
+-  **Reliable Federation and Decentralization:** No spam or IP reputation checks, federating
+   depends on established IETF standards and protocols.
+
+
+How about interoperability with classic email servers?
+-------------------------------------------------------
+
+Generally, chatmail relays interoperate well with classic email servers.
+However, some chatmail relays may be blocked by Big-Tech email
+providers that use intransparent and proprietary techniques for scanning
+and looking at cleartext email messages between users, or because they
+use questionable IP-reputation systems that break interoperability.
+
+**Chatmail relays instead use and require strong cryptography, allowing
+anyone to participate, without having to submit to Big-Tech
+restrictions.**
+
+.. _selfhosted:
+
+How are chatmail relays run? Can I run one myself?
+--------------------------------------------------
+
+Chatmail relays are designed to be very cheap to run, and are generally
+self-funded by respective operators. All chatmail relays are
+automatically deployed and updated using `the chatmail relay
+repository <https://github.com/chatmail/relay>`__. Chatmail relays are
+composed of proven standard email server components, Postfix and
+Dovecot, and are configured to run unattended without much maintenance
+effort. Chatmail relays happily run on low-end hardware like a Raspberry
+Pi.
+
+
+How trustable are chatmail relays?
+----------------------------------
+
+Chatmail relays enforce end-to-end encryption,
+and chatmail clients like `Delta Chat <https://delta.chat>`_
+enforce end-to-end encryption on their own.
+
+The end-to-end encryption protection includes attached media, user
+display names, avatars and group names. What is visible to operators is:
+message date, sender and receiver addresses.
+Please see the `Delta Chat FAQ on encryption and security <https://delta.chat/en/help#e2ee>`_ for further info.

doc/source/getting_started.rst

@@ -0,0 +1,169 @@
+Setting up a chatmail relay
+===========================
+
+This section contains everything needed to setup a ready-to-use chatmail relay.
+The automated setup is designed and optimized for providing chatmail
+addresses for immediate permission-free onboarding through chat apps and bots.
+Chatmail addresses are automatically created at first login,
+after which the initially specified password is required
+for sending and receiving messages through them.
+
+
+Minimal requirements and prerequisites
+--------------------------------------
+
+You will need the following:
+
+-  Control over a domain through a DNS provider of your choice.
+
+-  A Debian 12 server with reachable SMTP/SUBMISSIONS/IMAPS/HTTPS ports.
+   IPv6 is encouraged if available. Chatmail relay servers only require
+   1GB RAM, one CPU, and perhaps 10GB storage for a few thousand active
+   chatmail addresses.
+
+-  Key-based SSH authentication to the root user. You must add a
+   passphrase-protected private key to your local ssh-agent because you
+   can’t type in your passphrase during deployment. (An ed25519 private
+   key is required due to an `upstream bug in
+   paramiko <https://github.com/paramiko/paramiko/issues/2191>`_)
+
+
+Setup with ``scripts/cmdeploy``
+-------------------------------------
+
+We use ``chat.example.org`` as the chatmail domain in the following
+steps. Please substitute it with your own domain.
+
+1. Setup the initial DNS records. The following is an example in the
+   familiar BIND zone file format with a TTL of 1 hour (3600 seconds).
+   Please substitute your domain and IP addresses.
+
+   ::
+
+       chat.example.com. 3600 IN A 198.51.100.5
+       chat.example.com. 3600 IN AAAA 2001:db8::5
+       www.chat.example.com. 3600 IN CNAME chat.example.com.
+       mta-sts.chat.example.com. 3600 IN CNAME chat.example.com.
+
+2. On your local PC, clone the repository and bootstrap the Python
+   virtualenv.
+
+   ::
+
+       git clone https://github.com/chatmail/relay
+       cd relay
+       scripts/initenv.sh
+
+3. On your local PC, create chatmail configuration file
+   ``chatmail.ini``:
+
+   ::
+
+       scripts/cmdeploy init chat.example.org  # <-- use your domain
+
+4. Verify that SSH root login to your remote server works:
+
+   ::
+
+       ssh root@chat.example.org  # <-- use your domain
+
+5. From your local PC, deploy the remote chatmail relay server:
+
+   ::
+
+       scripts/cmdeploy run
+
+   This script will also check that you have all necessary DNS records.
+   If DNS records are missing, it will recommend which you should
+   configure at your DNS provider (it can take some time until they are
+   public).
+
+Other helpful commands
+----------------------
+
+To check the status of your remotely running chatmail service:
+
+::
+
+   scripts/cmdeploy status
+
+To display and check all recommended DNS records:
+
+::
+
+   scripts/cmdeploy dns
+
+To test whether your chatmail service is working correctly:
+
+::
+
+   scripts/cmdeploy test
+
+To measure the performance of your chatmail service:
+
+::
+
+   scripts/cmdeploy bench
+
+
+
+Modifying the home page
+-----------------------
+
+``cmdeploy run`` also creates default static web pages and deploys them
+to a Nginx web server with:
+
+-  a default ``index.html`` along with a QR code that users can click to
+   create an address on your chatmail relay
+
+-  a default ``info.html`` that is linked from the home page
+
+-  a default ``policy.html`` that is linked from the home page
+
+All ``.html`` files are generated by the according markdown ``.md`` file
+in the ``www/src`` directory.
+
+Refining the web pages
+----------------------
+
+::
+
+   scripts/cmdeploy webdev
+
+This starts a local live development cycle for chatmail web pages:
+
+-  uses the ``www/src/page-layout.html`` file for producing static HTML
+   pages from ``www/src/*.md`` files
+
+-  continously builds the web presence reading files from ``www/src``
+   directory and generating HTML files and copying assets to the
+   ``www/build`` directory.
+
+-  Starts a browser window automatically where you can “refresh” as
+   needed.
+
+Custom web pages
+----------------
+
+You can skip uploading a web page by setting ``www_folder=disabled`` in
+``chatmail.ini``.
+
+If you want to manage your web pages outside this git repository, you
+can set ``www_folder`` in ``chatmail.ini`` to a custom directory on your
+computer. ``cmdeploy run`` will upload it as the server’s home page, and
+if it contains a ``src/index.md`` file, will build it with hugo.
+
+
+Disable automatic address creation
+--------------------------------------------------------
+
+If you need to stop address creation, e.g. because some script is wildly
+creating addresses, login with ssh and run:
+
+::
+
+       touch /etc/chatmail-nocreate
+
+Chatmail address creation will be denied while this file is present.
+
+

doc/source/index.rst

@@ -0,0 +1,20 @@
+*******************************************
+chatmail relay documentation
+*******************************************
+
+.. image:: ../../www/src/collage-top.png
+   :target: https://testrun.org
+
+This documentation details how to setup, maintain and understand `chatmail <https://chatmail.at>`_ relays.
+
+Contributions and feedback welcome through the https://github.com/chatmail/relay repository.
+
+.. toctree::
+    :maxdepth: 5
+
+    getting_started
+    proxy
+    migrate
+    overview
+    related
+    faq

doc/source/migrate.rst

@@ -0,0 +1,73 @@
+
+Migrating to a new host
+-----------------------
+
+If you want to migrate chatmail relay from an old machine to a new
+machine, you can use these steps. They were tested with a Linux laptop;
+you might need to adjust some of the steps to your environment.
+
+Let’s assume that your ``mail_domain`` is ``mail.example.org``, all
+involved machines run Debian 12, your old site’s IP address is
+``13.37.13.37``, and your new site’s IP address is ``13.12.23.42``.
+
+Note, you should lower the TTLs of your DNS records to a value such as
+300 (5 minutes) so the migration happens as smoothly as possible.
+
+During the guide you might get a warning about changed SSH Host keys; in
+this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended.
+
+1. First, disable mail services on the old site.
+
+   ::
+
+       cmdeploy run --disable-mail --ssh-host 13.37.13.37
+
+   Now your users will notice the migration and will not be able to send
+   or receive messages until the migration is completed.
+
+2. Now we want to copy ``/home/vmail``, ``/var/lib/acme``,
+   ``/etc/dkimkeys``, ``/run/echobot``, and ``/var/spool/postfix`` to
+   the new site. Login to the old site while forwarding your SSH agent
+   so you can copy directly from the old to the new site with your SSH
+   key:
+
+   ::
+
+       ssh -A root@13.37.13.37
+       tar c - /home/vmail/mail /var/lib/acme /etc/dkimkeys /run/echobot /var/spool/postfix | ssh root@13.12.23.42 "tar x -C /"
+
+   This transfers all addresses, the TLS certificate, DKIM keys (so DKIM
+   DNS record remains valid), and the echobot’s password so it continues
+   to function. It also preserves the Postfix mail spool so any messages
+   pending delivery will still be delivered.
+
+3. Install chatmail on the new machine:
+
+   ::
+
+       cmdeploy run --disable-mail --ssh-host 13.12.23.42
+
+   Postfix and Dovecot are disabled for now; we will enable them later.
+   We first need to make the new site fully operational.
+
+4. On the new site, run the following to ensure the ownership is correct
+   in case UIDs/GIDs changed:
+
+   ::
+
+       chown root: -R /var/lib/acme
+       chown opendkim: -R /etc/dkimkeys
+       chown vmail: -R /home/vmail/mail
+       chown echobot: -R /run/echobot
+
+5. Now, update DNS entries.
+
+   If other MTAs try to deliver messages to your chatmail domain they
+   may fail intermittently, as DNS catches up with the new site settings
+   but normally will retry delivering messages for at least a week, so
+   messages will not be lost.
+
+6. Finally, you can execute ``cmdeploy run --ssh-host 13.12.23.42`` to
+   turn on chatmail on the new relay. Your users will be able to use the
+   chatmail relay as soon as the DNS changes have propagated. Voilà!
+

doc/source/overview.rst

@@ -0,0 +1,344 @@
+
+Technical overview
+======================
+
+
+Directories of the relay repository
+-----------------------------------
+
+The `chatmail relay repository <https://github.com/chatmail/relay/tree/main/>`_
+has four main directories.
+
+``scripts/``
+~~~~~~~~~~~~~
+
+`scripts <https://github.com/chatmail/relay/tree/main/scripts>`_
+offers two convenience tools for beginners:
+
+- ``initenv.sh`` installs a local virtualenv Python environment and
+  installs necessary dependencies
+
+- ``scripts/cmdeploy`` script enables you to run the ``cmdeploy``
+  command line tool in the local Python virtual environment.
+
+
+``cmdeploy/``
+~~~~~~~~~~~~~
+
+The ``cmdeploy`` directory contains the Python package and command line tool
+to setup a chatmail relay remotely via SSH:
+
+- ``cmdeploy init`` creates the ``chatmail.ini`` config file locally.
+
+- ``cmdeploy run`` under the hood uses pyinfra_
+  to automatically install or upgrade all chatmail components on a relay,
+  according to the local ``chatmail.ini`` config.
+
+The deployed system components of a chatmail relay are:
+
+-  Postfix_ is the Mail Transport Agent (MTA) and
+   accepts messages from, and sends messages to, the wider email MTA network
+
+-  Dovecot_ is the Mail Delivery Agent (MDA) and
+   stores messages for users until they download them
+
+-  Nginx_ shows the web page with privacy policy and additional information
+
+-  `acmetool <https://hlandau.github.io/acmetool/>`_ manages TLS
+   certificates for Dovecot, Postfix, and Nginx
+
+-  `OpenDKIM <http://www.opendkim.org/>`_ for signing messages with
+   DKIM and rejecting inbound messages without DKIM
+
+-  `mtail <https://google.github.io/mtail/>`_ for collecting anonymized
+   metrics in case you have monitoring
+
+-  `Iroh relay <https://www.iroh.computer/docs/concepts/relay>`_ which
+   helps client devices to establish Peer-to-Peer connections
+
+-  `TURN <https://github.com/chatmail/chatmail-turn>`_ to enable relay
+   users to start webRTC calls even if a p2p connection can’t be
+   established
+
+-  and the chatmaild services, explained in the next section:
+
+
+``chatmaild/``
+~~~~~~~~~~~~~~
+
+`chatmaild <https://github.com/chatmail/relay/tree/main/chatmaild>`_
+is a Python package containing several small services which handle
+authentication, trigger push notifications on new messages, ensure
+that outbound mails are encrypted, delete inactive users, and some
+other minor things. chatmaild can also be installed as a stand-alone
+Python package.
+
+``chatmaild`` implements various systemd-controlled services
+that integrate with Dovecot and Postfix to achieve instant-onboarding
+and only relaying OpenPGP end-to-end messages encrypted messages. A
+short overview of ``chatmaild`` services:
+
+-  `doveauth <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/doveauth.py>`_
+   implements create-on-login address semantics and is used by Dovecot
+   during IMAP login and by Postfix during SMTP/SUBMISSION login which
+   in turn uses `Dovecot SASL
+   <https://doc.dovecot.org/2.3/configuration_manual/authentication/dict/#complete-example-for-authenticating-via-a-unix-socket>`_
+   to authenticate logins.
+
+-  `filtermail <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/filtermail.py>`_
+   prevents unencrypted email from leaving or entering the chatmail
+   service and is integrated into Postfix’s outbound and inbound mail
+   pipelines.
+
+-  `chatmail-metadata <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/metadata.py>`_
+   is contacted by a `Dovecot lua
+   script <https://github.com/chatmail/relay/blob/main/cmdeploy/src/cmdeploy/dovecot/push_notification.lua>`_
+   to store user-specific relay-side config. On new messages, it `passes
+   the user’s push notification
+   token <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/notifier.py>`_
+   to
+   `notifications.delta.chat <https://delta.chat/en/help#instant-delivery>`_
+   so the push notifications on the user’s phone can be triggered by
+   Apple/Google/Huawei.
+
+-  `chatmail-expire <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/expire.py>`_
+   deletes users if they have not logged in for a longer while.
+   The timeframe can be configured in ``chatmail.ini``.
+
+-  `lastlogin <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/lastlogin.py>`_
+   is contacted by Dovecot when a user logs in and stores the date of
+   the login.
+
+-  `echobot <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/echo.py>`_
+   is a small bot for test purposes. It simply echoes back messages from
+   users.
+
+-  `metrics <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/metrics.py>`_
+   collects some metrics and displays them at
+   ``https://example.org/metrics``.
+
+``www/``
+~~~~~~~~~
+
+`www <https://github.com/chatmail/relay/tree/main/www>`_ contains
+the html, css, and markdown files which make up a chatmail relay’s
+web page. Edit them before deploying to make your chatmail relay
+stand out.
+
+
+Component dependency diagram
+--------------------------------------
+
+.. mermaid::
+   :caption: This diagram shows relay components and dependencies/communication paths.
+
+    graph LR;
+        cmdeploy --- sshd;
+        letsencrypt --- |80|acmetool-redirector;
+        acmetool-redirector --- |443|nginx-right(["`nginx
+        (external)`"]);
+        nginx-external --- |465|postfix;
+        nginx-external(["`nginx
+        (external)`"]) --- |8443|nginx-internal["`nginx
+        (internal)`"];
+        nginx-internal --- website["`Website
+        /var/www/html`"];
+        nginx-internal --- newemail.py;
+        nginx-internal --- autoconfig.xml;
+        certs-nginx[("`TLS certs
+        /var/lib/acme`")] --> nginx-internal;
+        cron --- chatmail-metrics;
+        cron --- acmetool;
+        chatmail-metrics --- website;
+        acmetool --> certs[("`TLS certs
+        /var/lib/acme`")];
+        nginx-external --- |993|dovecot;
+        autoconfig.xml --- postfix;
+        autoconfig.xml --- dovecot;
+        postfix --- echobot;
+        postfix --- |10080,10081|filtermail;
+        postfix --- users["`User data
+        home/vmail/mail`"];
+        postfix --- |doveauth.socket|doveauth;
+        dovecot --- |doveauth.socket|doveauth;
+        dovecot --- users;
+        dovecot --- |metadata.socket|chatmail-metadata;
+        doveauth --- users;
+        chatmail-expire-daily --- users;
+        chatmail-fsreport-daily --- users;
+        chatmail-metadata --- iroh-relay;
+        certs-nginx --> postfix;
+        certs-nginx --> dovecot;
+        style certs fill:#ff6;
+        style certs-nginx fill:#ff6;
+        style nginx-external fill:#fc9;
+        style nginx-right fill:#fc9;
+
+
+Operational details of a chatmail relay
+----------------------------------------
+
+Mailbox directory layout
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Fresh chatmail addresses have a mailbox directory that contains:
+
+-  a ``password`` file with the salted password required for
+   authenticating whether a login may use the address to send/receive
+   messages. If you modify the password file manually, you effectively
+   block the user.
+
+-  ``enforceE2EEincoming`` is a default-created file with each address.
+   If present the file indicates that this chatmail address rejects
+   incoming cleartext messages. If absent the address accepts incoming
+   cleartext messages.
+
+-  ``dovecot*``, ``cur``, ``new`` and ``tmp`` represent IMAP/mailbox
+   state. If the address is only used by one device, the Maildir
+   directories will typically be empty unless the user of that address
+   hasn’t been online for a while.
+
+Active ports
+~~~~~~~~~~~~
+
+Postfix_ listens on ports
+
+- 25 (SMTP)
+
+- 587 (SUBMISSION) and
+
+- 465 (SUBMISSIONS)
+
+Dovecot_ listens on ports
+
+- 143 (IMAP) and
+
+- 993 (IMAPS)
+
+Nginx_ listens on port
+
+- 8443 (HTTPS-ALT) and
+
+- 443 (HTTPS) which multiplexes HTTPS, IMAP and SMTP using ALPN
+  to redirect connections to ports 8443, 465 or 993.
+
+`acmetool <https://hlandau.github.io/acmetool/>`_ listens on port:
+
+- 80 (HTTP).
+
+`chatmail-turn <https://github.com/chatmail/chatmail-turn>`_ listens on port
+
+- 3478 UDP (STUN/TURN), and temporarily opens further UDP ports
+  when users request them. UDP port range is not restricted, any free port
+  may be allocated.
+
+chatmail-core based apps will, however, discover all ports and
+configurations automatically by reading the `autoconfig XML
+file <https://www.ietf.org/archive/id/draft-bucksch-autoconfig-00.html>`_
+from the chatmail relay server.
+
+Email domain authentication (DKIM)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Chatmail relays enforce :rfc:`DKIM <6376>` to authenticate incoming emails.
+Incoming emails must have a valid DKIM signature with
+Signing Domain Identifier (SDID, ``d=`` parameter in the DKIM-Signature
+header) equal to the ``From:`` header domain. This property is checked
+by OpenDKIM screen policy script before validating the signatures. This
+correpsonds to strict :rfc:`DMARC <7489>` alignment (``adkim=s``).
+If there is no valid DKIM signature on the incoming email, the
+sender receives a “5.7.1 No valid DKIM signature found” error.
+
+Note that chatmail relays
+
+- do **not** rely on DMARC and do not consult the sender policy published in DMARC records;
+
+- do **not** rely on legacy authentication mechanisms such as
+  :rfc:`iprev <8601#section-2.7.3>` and :rfc:`SPF <7208>`.
+  Any IP address is accepted if the DKIM signature was valid.
+
+Outgoing emails must be sent over authenticated connection with envelope
+``MAIL FROM`` (return path) corresponding to the login.
+This is ensured by Postfix which maps login username to ``MAIL FROM`` with
+`smtpd_sender_login_maps <https://www.postfix.org/postconf.5.html#smtpd_sender_login_maps>`_
+and rejects incorrectly authenticated emails with
+`reject_sender_login_mismatch <https://www.postfix.org/postconf.5.html#reject_sender_login_mismatch>`_ policy.
+``From:`` header must correspond to envelope ``MAIL FROM``, this is
+ensured by ``filtermail`` proxy.
+
+TLS requirements
+~~~~~~~~~~~~~~~~
+
+Postfix is configured to require valid TLS by setting
+`smtp_tls_security_level <https://www.postfix.org/postconf.5.html#smtp_tls_security_level>`_
+to ``verify``. If emails don’t arrive at your chatmail relay server, the
+problem is likely that your relay does not have a valid TLS certificate.
+
+You can test it by resolving ``MX`` records of your relay domain and
+then connecting to MX relays (e.g ``mx.example.org``) with
+``openssl s_client -connect mx.example.org:25 -verify_hostname mx.example.org -verify_return_error -starttls smtp``
+from the host that has open port 25 to verify that certificate is valid.
+
+When providing a TLS certificate to your chatmail relay server, make
+sure to provide the full certificate chain and not just the last
+certificate.
+
+If you are running an Exim server and don’t see incoming connections
+from a chatmail relay server in the logs, make sure ``smtp_no_mail`` log
+item is enabled in the config with ``log_selector = +smtp_no_mail``. By
+default Exim does not log sessions that are closed before sending the
+``MAIL`` command. This happens if certificate is not recognized as valid
+by Postfix, so you might think that connection is not established while
+actually it is a problem with your TLS certificate.
+
+
+.. _dovecot: https://dovecot.org
+.. _postfix: https://www.postfix.org
+.. _nginx: https://nginx.org
+.. _pyinfra: https://pyinfra.com
+
+
+Architecture of cmdeploy
+------------------------
+
+cmdeploy is a Python program that uses the pyinfra library to deploy
+chatmail relays, with all the necessary software, configuration, and
+services.  The deployment process performs three primary types of
+operation:
+
+1. Installation of software, universal across all deployments.
+2. Configuration of software, with deploy-specific variations.
+3. Activation of services.
+
+The process is implemented through a family of "deployer" objects
+which all derive from a common ``Deployer`` base class, defined in
+cmdeploy/src/cmdeploy/deployer.py.  Each object provides
+implementation methods for the three stages -- install, configure, and
+activate.  The top-level procedure in ``deploy_chatmail()`` calls
+these methods for all the deployer objects, via the
+``Deployment.perform_stages()`` method, also defined in deployer.py.
+This first calls all the install methods, then the configure methods,
+then the activate methods.
+
+The ``Deployment`` class also implements support for a CMDEPLOY_STAGES
+environment variable, which allows limiting the process to specific
+stages.  Note that some deployers are stateful between the stages
+(this is one reason why they are implemented as objects), and that
+state will not get propagated between stages when run in separate
+invocations of cmdeploy.  This environment variable is intended for
+use in future revisions to support building Docker images with
+software pre-installed, and configuration of containers at run time
+from environment variables.
+
+The, ``install()`` methods for the deployer classes should use 'self'
+as little as possible, preferably not at all.  In particular,
+``install()`` methods should never depend on "config" data, such as
+the config dictionary in ``self.config`` or specific values like
+``self.mail_domain``.  This ensures that these methods can be used to
+perform generic installation operations that are applicable across
+multiple relay deployments, and therefore can be called in the process
+of building a general-purpose container image.
+
+Operations that start services for systemd-based deployments should
+only be called from the ``activate_impl()`` methods.  These methods
+will not be called in non-systemd container environments.

doc/source/proxy.rst

@@ -0,0 +1,114 @@
+
+Setting up a reverse proxy
+--------------------------
+
+A chatmail relay MTA does not track or depend on the client IP address
+for its operation, so it can be run behind a reverse proxy. This will
+not even affect incoming mail authentication as DKIM only checks the
+cryptographic signature of the message and does not use the IP address
+as the input.
+
+For example, you may want to self-host your chatmail relay and only use
+hosted VPS to provide a public IP address for client connections and
+incoming mail. You can connect chatmail relay to VPS using a tunnel
+protocol such as `WireGuard <https://www.wireguard.com/>`_ and setup a
+reverse proxy on a VPS to forward connections to the chatmail relay over
+the tunnel. You can also setup multiple reverse proxies for your
+chatmail relay in different networks to ensure your relay is reachable
+even when one of the IPs becomes inaccessible due to hosting or routing
+problems.
+
+Note that your chatmail relay still needs to be able to make outgoing
+connections on port 25 to send messages outside.
+
+To setup a reverse proxy (or rather Destination NAT, DNAT) for your
+chatmail relay, put the following configuration in
+``/etc/nftables.conf``:
+
+::
+
+   #!/usr/sbin/nft -f
+
+   flush ruleset
+
+   define wan = eth0
+
+   # Which ports to proxy.
+   #
+   # Note that SSH is not proxied
+   # so it is possible to log into the proxy server
+   # and not the original one.
+   define ports = { smtp, http, https, imap, imaps, submission, submissions }
+
+   # The host we want to proxy to.
+   define ipv4_address = AAA.BBB.CCC.DDD
+   define ipv6_address = [XXX::1]
+
+   table ip nat {
+           chain prerouting {
+                   type nat hook prerouting priority dstnat; policy accept;
+                   iif $wan tcp dport $ports dnat to $ipv4_address
+           }
+
+           chain postrouting {
+                   type nat hook postrouting priority 0;
+
+                   oifname $wan masquerade
+           }
+   }
+
+   table ip6 nat {
+           chain prerouting {
+                   type nat hook prerouting priority dstnat; policy accept;
+                   iif $wan tcp dport $ports dnat to $ipv6_address
+           }
+
+           chain postrouting {
+                   type nat hook postrouting priority 0;
+
+                   oifname $wan masquerade
+           }
+   }
+
+   table inet filter {
+           chain input {
+                   type filter hook input priority filter; policy drop;
+
+                   # Accept ICMP.
+                   # It is especially important to accept ICMPv6 ND messages,
+                   # otherwise IPv6 connectivity breaks.
+                   icmp type { echo-request } accept
+                   icmpv6 type { echo-request, nd-neighbor-solicit, nd-router-advert, nd-neighbor-advert } accept
+
+                   # Allow incoming SSH connections.
+                   tcp dport { ssh } accept
+
+                   ct state established accept
+           }
+           chain forward {
+                   type filter hook forward priority filter; policy drop;
+
+                   ct state established accept
+                   ip daddr $ipv4_address counter accept
+                   ip6 daddr $ipv6_address counter accept
+           }
+           chain output {
+                   type filter hook output priority filter;
+           }
+   }
+
+Run ``systemctl enable nftables.service`` to ensure configuration is
+reloaded when the proxy relay reboots.
+
+Uncomment in ``/etc/sysctl.conf`` the following two lines:
+
+::
+
+   net.ipv4.ip_forward=1
+   net.ipv6.conf.all.forwarding=1
+
+Then reboot the relay or do ``sysctl -p`` and
+``nft -f /etc/nftables.conf``.
+
+Once proxy relay is set up, you can add its IP address to the DNS.
+

doc/source/related.rst

@@ -0,0 +1,20 @@
+
+Community developments
+======================
+
+Active development takes place in the `chatmail/relay github repository <https://github.com/chatmail/relay>`_.
+
+You can check out the `'chatmail' tag in the support.delta.chat forum <https://support.delta.chat/tag/chatmail>`_
+and ask to get added to a non-public support chat for debugging issues.
+
+We know of two work-in-progress alternative implementation efforts:
+
+-  `Mox <https://github.com/mjl-/mox>`_: A Golang email server. `Work
+   is in progress <https://github.com/mjl-/mox/issues/251>`_ to modify
+   it to support all of the features and configuration settings required
+   to operate as a chatmail relay.
+
+-  `Maddy-Chatmail <https://github.com/sadraiiali/maddy_chatmail>`_: a
+   plugin for the `Maddy email server <https://maddy.email/>`_ which
+   aims to implement the chatmail relay features and configuration
+   options.

scripts/build-docs.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+#
+# Wrapper for building the docs
+set -e
+. venv/bin/activate
+cd doc/
+make html

scripts/initenv.sh

@@ -22,3 +22,4 @@ python3 -m venv --upgrade-deps venv
 
 venv/bin/pip install -e chatmaild 
 venv/bin/pip install -e cmdeploy
+venv/bin/pip install sphinx sphinxcontrib-mermaid sphinx-autobuild furo  # for building the docs