From babdff361cdf529fc4beebf3a3278a27c61b9bc7 Mon Sep 17 00:00:00 2001 From: missytake Date: Tue, 15 Oct 2024 14:54:51 +0200 Subject: [PATCH] docs: more details for the repo overview #419 --- README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 65 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index e841fab6..35261f57 100644 --- a/README.md +++ b/README.md @@ -80,31 +80,81 @@ scripts/cmdeploy bench ## Overview of this repository -This repository drives the development of chatmail services, -comprised of minimal setups of +This repository has four directories: -- [postfix smtp server](https://www.postfix.org) -- [dovecot imap server](https://www.dovecot.org) +- [cmdeploy](https://github.com/deltachat/chatmail/tree/main/cmdeploy) + is a collection of configuration files + and a [pyinfra](https://pyinfra.com)-based deployment script. +- [chatmaild](https://github.com/deltachat/chatmail/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/deltachat/chatmail/tree/main/www) + contains the html, css, and markdown files + which make up a chatmail server's web page. + Edit them before deploying to make your chatmail server stand out. +- [scripts](https://github.com/deltachat/chatmail/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. -as well as custom services that are integrated with these two: +### cmdeploy -- `chatmaild/src/chatmaild/doveauth.py` implements +The `cmdeploy/src/cmdeploy/cmdeploy.py` command line tool +helps with setting up and managing the chatmail service. +`cmdeploy run` uses [pyinfra-based scripting](https://pyinfra.com/) +in `cmdeploy/src/cmdeploy/__init__.py` +to automatically install all chatmail components on a server: + +- [postfix smtp server](https://www.postfix.org) accepts sent messages (both from your users and from other servers) +- [dovecot imap server](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 +- and the chatmaild services, explained in the next section: + +### chatmaild + +chatmaild offers several commands +which differentiate a *chatmail* server from a classic mail server. +If you deploy them with cmdeploy, +they are run by systemd services in the background. +A short overview: + +- [`doveauth`](https://github.com/deltachat/chatmail/blob/main/chatmaild/src/chatmaild/doveauth.py) implements create-on-login account creation semantics and is used by Dovecot during login authentication and by Postfix which in turn uses [Dovecot SASL](https://doc.dovecot.org/configuration_manual/authentication/dict/#complete-example-for-authenticating-via-a-unix-socket) to authenticate users to send mails for them. - -- `chatmaild/src/chatmaild/filtermail.py` prevents +- [`filtermail`](https://github.com/deltachat/chatmail/blob/main/chatmaild/src/chatmaild/filtermail.py) prevents unencrypted e-mail from leaving the chatmail service and is integrated into postfix's outbound mail pipelines. - -There is also the `cmdeploy/src/cmdeploy/cmdeploy.py` command line tool -which helps with setting up and managing the chatmail service. -`cmdeploy run` uses [pyinfra-based scripting](https://pyinfra.com/) -in `cmdeploy/src/cmdeploy/__init__.py` -to automatically install all chatmail components on a server. - +- [`chatmail-metadata`](https://github.com/deltachat/chatmail/blob/main/chatmaild/src/chatmaild/metadata.py) is contacted by a + [dovecot lua script](https://github.com/deltachat/chatmail/blob/main/cmdeploy/src/cmdeploy/dovecot/push_notification.lua) + to store user-specific server-side config. + On new messages, + it [passes the user's push notification token](https://github.com/deltachat/chatmail/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. +- [`delete_inactive_users`](https://github.com/deltachat/chatmail/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/deltachat/chatmail/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/deltachat/chatmail/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/deltachat/chatmail/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