From dc9aebcb5535d9958bc156730cb4b7e06d751386 Mon Sep 17 00:00:00 2001 From: missytake Date: Wed, 13 Dec 2023 19:10:20 +0100 Subject: [PATCH] README: rework and reorder --- README.md | 186 ++++++++++++++++++++++++++---------------------------- 1 file changed, 91 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index bcf21494..b9ad0219 100644 --- a/README.md +++ b/README.md @@ -18,14 +18,7 @@ after which the initially specified password is required for using them. We subsequently use `CHATMAIL_DOMAIN` as a placeholder for your fully qualified DNS domain name (FQDN), for example `chat.example.org`. -1. Setup DNS `A` and `AAAA` records for your `CHATMAIL_DOMAIN`. - Verify that DNS is set and SSH root login works: - - ``` - ssh root@CHATMAIL_DOMAIN - ``` - -2. Install the `cmdeploy` command in a virtualenv +1. Install the `cmdeploy` command in a virtualenv ``` git clone https://github.com/deltachat/chatmail @@ -33,12 +26,20 @@ DNS domain name (FQDN), for example `chat.example.org`. scripts/initenv.sh ``` -3. Create chatmail configuration file `chatmail.ini`: +2. Create chatmail configuration file `chatmail.ini`: ``` scripts/cmdeploy init CHATMAIL_DOMAIN ``` +3. Setup first DNS records for your `CHATMAIL_DOMAIN`, + according to the hints provided by `cmdeploy init`. + Verify that SSH root login works: + + ``` + ssh root@CHATMAIL_DOMAIN + ``` + 4. Deploy to the remote chatmail server: ``` @@ -52,111 +53,106 @@ DNS domain name (FQDN), for example `chat.example.org`. scripts/cmdeploy dns ``` -6. To check status of your remotely running chatmail service: +### Other helpful commands: - ``` - scripts/cmdeploy status - ``` +To check the status of your remotely running chatmail service: -7. To test your chatmail service: - - ``` - scripts/cmdeploy test - ``` - -8. To benchmark your chatmail service: - - ``` - scripts/cmdeploy bench - ``` - -### Refining the web pages - - -``` - scripts/cmdeploy webdev +``` +scripts/cmdeploy status ``` -This starts a local live development cycle for chatmail Web pages: +To test whether your chatmail service is working correctly: -- uses the `www/src/page-layout.html` file for producing static - HTML pages from `www/src/*.md` files +``` +scripts/cmdeploy test +``` -- continously builds the web presence reading files from `www/src` directory - and generating html files and copying assets to the `www/build` directory. +To measure the performance of your chatmail service: -- Starts a browser window automatically where you can "refresh" as needed. +``` +scripts/cmdeploy bench +``` +## Overview of this repository -### Home page and getting started for users +This repository drives the development of "chatmail instances", +comprised of minimal setups of -`cmdeploy run` sets up mail services, -and also creates default static Web pages and deploys them: +- [postfix smtp server](https://www.postfix.org) +- [dovecot imap server](https://www.dovecot.org) -- a default `index.html` along with a QR code that users can click to - create accounts on your chatmail provider, - -- 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. - - -### Ports - -Postfix listens on ports 25 (smtp) and 587 (submission) and 465 (submissions). -Dovecot listens on ports 143(imap) and 993 (imaps). - -Delta Chat will, however, discover all ports and configurations -automatically by reading the `autoconfig.xml` file from the chatmail instance. - - -## Emergency Commands to disable automatic account creation - -If you need to stop account creation, -e.g. because some script is wildly creating accounts, run: - - touch /etc/chatmail-nocreate - -While this file is present, account creation will be blocked. - - -## Running tests and benchmarks (offline and online) - -1. Set `CHATMAIL_SSH` so that `ssh root@$CHATMAIL_SSH` allows - to login to the chatmail instance server. - -2. To run local and online tests: - - scripts/test.sh - -3. To run benchmarks against your chatmail instance: - - scripts/bench.sh - - -## Development Background for chatmail instances - -This repository drives the development of "chatmail instances", -comprised of minimal setups of - -- [postfix smtp server](https://www.postfix.org) -- [dovecot imap server](https://www.dovecot.org) - -as well as two custom services that are integrated with these two: +as well as custom services that are integrated with these two: - `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. + to send mails for them. -- `chatmaild/src/chatmaild/filtermail.py` prevents +- `chatmaild/src/chatmaild/filtermail.py` prevents unencrypted e-mail from leaving the chatmail instance - and is integrated into postfix's outbound mail pipelines. + 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. +### Home page and getting started for users + +`cmdeploy run` also creates default static Web pages and deploys them +to an nginx web server under `https://CHATMAIL_DOMAIN`. + +- a default `index.html` along with a QR code that users can click to + create accounts on your chatmail provider, + +- 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. + + +## Emergency Commands to disable automatic account creation + +If you need to stop account creation, +e.g. because some script is wildly creating accounts, +login to the server with ssh and run: + +``` + touch /etc/chatmail-nocreate +``` + +While this file is present, account creation will be blocked. + +### Ports + +Postfix listens on ports 25 (smtp) and 587 (submission) and 465 (submissions). +Dovecot listens on ports 143(imap) and 993 (imaps). + +Delta Chat apps will, however, discover all ports and configurations +automatically by reading the `autoconfig.xml` file from the chatmail service. +