mirror of
https://github.com/chatmail/relay.git
synced 2026-05-16 19:38:57 +00:00
Split README into sphinx doc structured sections (#711)
refactor README.rst and architecture file into sphinx doc project, automatically deploying on main merges and PRs. * add FAQs from https://chatmail.at/relays landing page * fix links, and streamline postfix/dovecot mentioning * add linkcheck to CI, fix several links and streamlihne DKIM section while at it * some streamlining, rename to "overview" * ci: upload documentation to chatmail.at/doc/relay * ci: main should be uploaded when docs.yaml changes * ci: fix typo * Update .github/workflows/docs-preview.yaml Co-authored-by: missytake <missytake@systemli.org>
This commit is contained in:
holger krekel
GitHub
169
doc/source/getting_started.rst
Normal file
169
doc/source/getting_started.rst
Normal file
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user