cqrenet/relay
4
0
Fork 0
mirror of https://github.com/chatmail/relay.git synced 2026-05-19 04:18:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

Split README into sphinx doc structured sections (#711)

Browse Source 
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
2025-11-11 14:49:25 +01:00
committed by GitHub
parent f24bc99c6f
commit 50b986a265
19 changed files with 1005 additions and 604 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
doc/source/migrate.rst Normal file
View File

@@ -0,0 +1,73 @@
Migrating to a new host
-----------------------
If you want to migrate chatmail relay from an old machine to a new
machine, you can use these steps. They were tested with a Linux laptop;
you might need to adjust some of the steps to your environment.
Let’s assume that your ``mail_domain`` is ``mail.example.org``, all
involved machines run Debian 12, your old site’s IP address is
``13.37.13.37``, and your new site’s IP address is ``13.12.23.42``.
Note, you should lower the TTLs of your DNS records to a value such as
300 (5 minutes) so the migration happens as smoothly as possible.
During the guide you might get a warning about changed SSH Host keys; in
this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended.
1. First, disable mail services on the old site.
::
cmdeploy run --disable-mail --ssh-host 13.37.13.37
Now your users will notice the migration and will not be able to send
or receive messages until the migration is completed.
2. Now we want to copy ``/home/vmail``, ``/var/lib/acme``,
``/etc/dkimkeys``, ``/run/echobot``, and ``/var/spool/postfix`` to
the new site. Login to the old site while forwarding your SSH agent
so you can copy directly from the old to the new site with your SSH
key:
::
ssh -A root@13.37.13.37
tar c - /home/vmail/mail /var/lib/acme /etc/dkimkeys /run/echobot /var/spool/postfix | ssh root@13.12.23.42 "tar x -C /"
This transfers all addresses, the TLS certificate, DKIM keys (so DKIM
DNS record remains valid), and the echobot’s password so it continues
to function. It also preserves the Postfix mail spool so any messages
pending delivery will still be delivered.
3. Install chatmail on the new machine:
::
cmdeploy run --disable-mail --ssh-host 13.12.23.42
Postfix and Dovecot are disabled for now; we will enable them later.
We first need to make the new site fully operational.
4. On the new site, run the following to ensure the ownership is correct
in case UIDs/GIDs changed:
::
chown root: -R /var/lib/acme
chown opendkim: -R /etc/dkimkeys
chown vmail: -R /home/vmail/mail
chown echobot: -R /run/echobot
5. Now, update DNS entries.
If other MTAs try to deliver messages to your chatmail domain they
may fail intermittently, as DNS catches up with the new site settings
but normally will retry delivering messages for at least a week, so
messages will not be lost.
6. Finally, you can execute ``cmdeploy run --ssh-host 13.12.23.42`` to
turn on chatmail on the new relay. Your users will be able to use the
chatmail relay as soon as the DNS changes have propagated. Voilà!