README: rework and reorder

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.
+