mirror of
https://github.com/chatmail/relay.git
synced 2026-05-10 16:04:37 +00:00
README: rework and reorder
This commit is contained in:
missytake
holger krekel
186
README.md
186
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.
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user