mirror of
https://github.com/chatmail/relay.git
synced 2026-05-10 07:54:36 +00:00
cf96be2cbb
feat: support self-signed TLS via underscore domain convention Domains starting with "_" (e.g. _chat.example.org) automatically use self-signed TLS certificates instead of ACME/Let's Encrypt. The TLS mode is derived from the domain name — no separate config option needed. Internally, when config.tls_cert_mode is "self" (underscore domain): - Generate self-signed certificates via openssl - Set Postfix smtp_tls_security_level to "encrypt" (opportunistic TLS) - Add smtp_tls_policy_map entry for underscore domains - Skip ACME, MTA-STS and www CNAME checks in `cmdeploy dns` - Serve /new via GET (not redirect to dcaccount:) with rate-limiting (nginx limit_req, 2r/s burst=5) - Return dclogin: URLs with ic=3 (AcceptInvalidCertificates) from /new - Render QR codes client-side via JavaScript and qrcode-svg - Use config.tls_cert_path/tls_key_path in Postfix, Dovecot and nginx templates instead of hardcoded ACME paths
221 lines
6.4 KiB
ReStructuredText
221 lines
6.4 KiB
ReStructuredText
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 **deployment 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.
|
||
|
||
- A Linux or Unix **build machine** with key-based SSH access to the root
|
||
user of the deployment server.
|
||
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 for your deployment server.
|
||
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.org. 3600 IN A 198.51.100.5
|
||
chat.example.org. 3600 IN AAAA 2001:db8::5
|
||
www.chat.example.org. 3600 IN CNAME chat.example.org.
|
||
mta-sts.chat.example.org. 3600 IN CNAME chat.example.org.
|
||
|
||
.. note::
|
||
|
||
For experimental deployments using self-signed certificates,
|
||
use a domain name starting with ``_``
|
||
(e.g. ``_chat.example.org``).
|
||
The ``mta-sts`` CNAME and ``_mta-sts`` TXT records
|
||
are not needed for such domains.
|
||
|
||
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 build machine (PC), create a chatmail configuration file
|
||
``chatmail.ini``:
|
||
|
||
::
|
||
|
||
scripts/cmdeploy init chat.example.org # <-- use your domain
|
||
|
||
To use self-signed TLS certificates
|
||
instead of Let's Encrypt,
|
||
use a domain name starting with ``_``
|
||
(e.g. ``scripts/cmdeploy init _chat.example.org``).
|
||
Domains starting with ``_`` cannot obtain WebPKI certificates,
|
||
so self-signed mode is derived automatically.
|
||
This is useful for private or test deployments.
|
||
See the :doc:`overview`
|
||
for details on certificate provisioning.
|
||
|
||
4. Verify that SSH root login to the deployment server server works:
|
||
|
||
::
|
||
|
||
ssh root@chat.example.org # <-- use your domain
|
||
|
||
5. From your local build machine, setup and configure the remote deployment 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 deployment server running the 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 to the deployment machine and run:
|
||
|
||
::
|
||
|
||
touch /etc/chatmail-nocreate
|
||
|
||
Chatmail address creation will be denied while this file is present.
|
||
|
||
|
||
Running a relay with self-signed certificates
|
||
----------------------------------------------
|
||
|
||
Use a domain name starting with ``_`` (e.g. ``_chat.example.org``)
|
||
to run a relay with self-signed certificates.
|
||
Domains starting with ``_`` cannot obtain WebPKI certificates
|
||
so the relay automatically uses self-signed certificates
|
||
and all other relays will accept connections from it
|
||
without requiring certificate verification.
|
||
This is useful for experimental setups and testing.
|
||
|
||
Migrating to a new build machine
|
||
----------------------------------
|
||
|
||
To move or add a build machine,
|
||
clone the relay repository on the new build machine, and copy the ``chatmail.ini`` file from the old build machine.
|
||
Make sure ``rsync`` is installed, then initialize the environment:
|
||
|
||
::
|
||
|
||
./scripts/initenv.sh
|
||
|
||
Run safety checks before a new deployment:
|
||
|
||
::
|
||
|
||
./scripts/cmdeploy dns
|
||
./scripts/cmdeploy status
|
||
|
||
If you keep multiple build machines (ie laptop and desktop), keep ``chatmail.ini`` in sync between
|
||
them.
|