From d1f95238368a3133f2ebaadfebb26c8a98f513db Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EF=BC=93=EF=BC=97=EF=BC=93?=
 <151577046+ccclxxiii@users.noreply.github.com>
Date: Sun, 4 Jan 2026 13:21:12 +0000
Subject: [PATCH] docs: adds instructions for migrating control machines (#795)

* docs: update index reference

* docs: adds control machine migration instructions

* docs: rename index ref

* docs: remove maddy-chatmail (404)

* docs: consistent underlining in header text

* docs: remove dedicated page reference

* docs: remove dedicated page for control machine migration

* docs: condense deployment machine migration into getting started per feedback

* docs: correct link to madmail

* docs: update verbiage based on feedback
---
 doc/source/getting_started.rst | 19 +++++++++++++++++++
 doc/source/related.rst         |  8 ++++----
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst
index e0ffb619..f31d2da6 100644
--- a/doc/source/getting_started.rst
+++ b/doc/source/getting_started.rst
@@ -166,4 +166,23 @@ creating addresses, login with ssh and run:
 
 Chatmail address creation will be denied while this file is present.
 
+Migrating to a new deployment machine
+----------------------------------
 
+To move or add a deployment machine, keep a copy of a working ``chatmail.ini``,
+clone the relay repo on the new machine, and recreate ``chatmail.ini`` there.
+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 deployment machines (ie laptop and desktop), keep ``chatmail.ini`` in sync between
+them.
diff --git a/doc/source/related.rst b/doc/source/related.rst
index 07845511..cecbef46 100644
--- a/doc/source/related.rst
+++ b/doc/source/related.rst
@@ -14,10 +14,10 @@ We know of three work-in-progress alternative implementation efforts:
    it to support all of the features and configuration settings required
    to operate as a chatmail relay.
 
--  `Maddy-Chatmail <https://github.com/sadraiiali/maddy_chatmail>`_: a
-   plugin for the `Maddy email server <https://maddy.email/>`_ which
-   aims to implement the chatmail relay features and configuration
-   options.
+-  `Madmail <https://github.com/omidz4t/madmail>`_: an
+   experimental fork of Maddy Mail Server <https://maddy.email/>`_ optimized
+   for chatmail deployments.  It provides a single binary solution
+   for running a chatmail relay.
 
 -  `Chatmail Cookbook <https://github.com/feld/chatmail-cookbook>`_:
    A Chef Cookbook implementing a relay server. The project follows the