fix(cmdeploy): check venv python versions and purge if mismatched

`cmdeploy run` failed after upgrade system upgrade to Debian 13 with
"Fatal Python error: init_fs_encoding: failed to get the Python codec of
the filesystem encoding" indicating a Python version missmatch. Check
for both versions and remove old `remote_venv_dir` on mismatch to allow
clean reinitialization by subsequent pip.virtualenv().

.github/workflows/docker-dispatch.yaml

@@ -8,7 +8,7 @@ name: Trigger Docker build
 
 on:
   push:
-    branches: [main]
+    branches: [main, j4n/dovecot-multidist]
     tags: ['[0-9]+.[0-9]+.[0-9]+']
   workflow_dispatch:
 

chatmaild/pyproject.toml

@@ -9,8 +9,7 @@ dependencies = [
   "iniconfig",
   "filelock",
   "requests",
-  "crypt-r >= 3.13.1 ; python_version >= '3.11'",
-  "domain-validator",
+  "crypt-r >= 3.13.1 ; python_version >= '3.13'",
 ]
 
 [tool.setuptools]

chatmaild/src/chatmaild/config.py

@@ -2,7 +2,6 @@ import ipaddress
 from pathlib import Path
 
 import iniconfig
-from domain_validator import DomainValidator
 
 from chatmaild.user import User
 
@@ -19,14 +18,12 @@ class Config:
         params = dict(params)
         raw_domain = params.pop("mail_domain")
         self.mail_domain_bare = raw_domain
-        self.ssh_host = params.pop("ssh_host", raw_domain)
 
         if is_valid_ipv4(raw_domain):
             self.ipv4_relay = raw_domain
             self.mail_domain = f"[{raw_domain}]"
             self.postfix_myhostname = ipaddress.IPv4Address(raw_domain).reverse_pointer
         else:
-            DomainValidator().validate_domain_re(raw_domain)
             self.ipv4_relay = None
             self.mail_domain = raw_domain
             self.postfix_myhostname = raw_domain

chatmaild/src/chatmaild/ini/chatmail.ini.f

@@ -3,9 +3,6 @@
 # mail domain (MUST be set to fully qualified chat mail domain)
 mail_domain = {mail_domain}
 
-# Where to deploy the relay - if unspecified, mail_domain will be used.
-ssh_host = localhost
-
 #
 # If you only do private test deploys, you don't need to modify any settings below
 #

cmdeploy/src/cmdeploy/acmetool/response-file.yaml.j2

@@ -1,2 +1,2 @@
 "acme-enter-email": "{{ email }}"
-"acme-agreement:https://letsencrypt.org/documents/LE-SA-v1.6-August-18-2025.pdf": true
+"acme-agreement:https://letsencrypt.org/documents/LE-SA-v1.7-June-04-2026.pdf": true

cmdeploy/src/cmdeploy/basedeploy.py

@@ -166,7 +166,7 @@ class Deployer:
             return self.put_template(src, dest, **kwargs)
         return self.put_file(src, dest)
 
-    def put_file(self, src, dest, mode="644"):
+    def put_file(self, src, dest, mode="644", **kwargs):
         if isinstance(src, str):
             src = get_resource(src)
         res = files.put(
@@ -176,6 +176,7 @@ class Deployer:
             user="root",
             group="root",
             mode=mode,
+            **kwargs,
         )
 
         return self._update_restart_signals(dest, res)

cmdeploy/src/cmdeploy/cmdeploy.py

@@ -96,7 +96,7 @@ def _warn_unused_settings(unused_keys, out):
 def run_cmd(args, out):
     """Deploy chatmail services on the remote server."""
 
-    ssh_host = args.ssh_host if args.ssh_host else args.config.ssh_host
+    ssh_host = args.ssh_host if args.ssh_host else args.config.mail_domain_bare
     sshexec = get_sshexec(ssh_host)
     require_iroh = args.config.enable_iroh_relay
     strict_tls = args.config.tls_cert_mode == "acme"
@@ -116,7 +116,7 @@ def run_cmd(args, out):
     pyinf = "pyinfra --dry" if args.dry_run else "pyinfra"
 
     cmd = f"{pyinf} --ssh-user root {ssh_host} {deploy_path} -y"
-    if ssh_host in ["localhost", "@local"]:
+    if ssh_host == "localhost":
         cmd = f"{pyinf} @local {deploy_path} -y"
 
     if version.parse(pyinfra.__version__) < version.parse("3"):
@@ -158,7 +158,7 @@ def dns_cmd(args, out):
         ipv4 = args.config.ipv4_relay
         print(f"[WARNING] {ipv4} is not a domain, skipping DNS checks.")
         return 0
-    ssh_host = args.ssh_host if args.ssh_host else args.config.ssh_host
+    ssh_host = args.ssh_host if args.ssh_host else args.config.mail_domain
     sshexec = get_sshexec(ssh_host, verbose=args.verbose)
     tls_cert_mode = args.config.tls_cert_mode
     strict_tls = tls_cert_mode == "acme"
@@ -195,7 +195,7 @@ def status_cmd_options(parser):
 def status_cmd(args, out):
     """Display status for online chatmail instance."""
 
-    ssh_host = args.ssh_host if args.ssh_host else args.config.ssh_host
+    ssh_host = args.ssh_host if args.ssh_host else args.config.mail_domain_bare
     sshexec = get_sshexec(ssh_host, verbose=args.verbose)
 
     out.green(f"chatmail domain: {args.config.mail_domain}")

cmdeploy/src/cmdeploy/deployers.py

@@ -98,6 +98,19 @@ def _install_remote_venv_with_chatmaild(deployer) -> None:
         dest=remote_dist_file,
     )
 
+    # Remove venv if its Python major.minor doesn't match the system Python
+    server.shell(
+        name="remove stale chatmaild venv if python version changed",
+        commands=["\n".join([
+            f"if [ -d {remote_venv_dir} ]; then",
+            r"  re='[0-9]+\.[0-9]+'",  # match major.minor from 'Python X.Y.Z'"
+            '   SYS_VERSION=$(python3 --version | grep -oE "$re")',
+            f'  VENV_VERSION=$({remote_venv_dir}/bin/python --version 2>/dev/null | grep -oE "$re")',
+            f'  [ "$SYS_VERSION" = "$VENV_VERSION" ] || rm -rf {remote_venv_dir}',
+            "fi",
+        ])],
+    )
+
     pip.virtualenv(
         name=f"chatmaild virtualenv {remote_venv_dir}",
         path=remote_venv_dir,
@@ -164,6 +177,7 @@ class UnboundDeployer(Deployer):
         self.put_file(
             src=BytesIO(b"nameserver 127.0.0.1\nnameserver 9.9.9.9\n"),
             dest="/etc/resolv.conf",
+            force=True,
         )
         server.shell(
             name="Generate root keys for validating DNSSEC",
@@ -389,6 +403,12 @@ class ChatmailDeployer(Deployer):
             src=BytesIO(b'APT::Install-Recommends "false";\n'),
             dest="/etc/apt/apt.conf.d/00InstallRecommends",
         )
+        # Pin dovecot-* to priority -1 before any apt operation, apt should
+        # never manage dovecot as our version might be lower than the distro's.
+        self.put_file(
+            src=StringIO("Package: dovecot-*\nPin: version *\nPin-Priority: -1\n"),
+            dest="/etc/apt/preferences.d/pin-dovecot",
+        )
         apt.update(name="apt update", cache_time=24 * 3600)
         apt.upgrade(name="upgrade apt packages", auto_remove=True)
 

cmdeploy/src/cmdeploy/dovecot/deployer.py

@@ -1,4 +1,3 @@
-import io
 import urllib.request
 
 from chatmaild.config import Config
@@ -19,12 +18,18 @@ DOVECOT_ARCHIVE_VERSION = "2.3.21+dfsg1-3"
 DOVECOT_PACKAGE_VERSION = f"1:{DOVECOT_ARCHIVE_VERSION}"
 
 DOVECOT_SHA256 = {
-    ("core", "amd64"): "dd060706f52a306fa863d874717210b9fe10536c824afe1790eec247ded5b27d",
-    ("core", "arm64"): "e7548e8a82929722e973629ecc40fcfa886894cef3db88f23535149e7f730dc9",
-    ("imapd", "amd64"): "8d8dc6fc00bbb6cdb25d345844f41ce2f1c53f764b79a838eb2a03103eebfa86",
-    ("imapd", "arm64"): "178fa877ddd5df9930e8308b518f4b07df10e759050725f8217a0c1fb3fd707f",
-    ("lmtpd", "amd64"): "2f69ba5e35363de50962d42cccbfe4ed8495265044e244007d7ccddad77513ab",
-    ("lmtpd", "arm64"): "89f52fb36524f5877a177dff4a713ba771fd3f91f22ed0af7238d495e143b38f",
+    ("amd64", "bookworm", "core"): "dd060706f52a306fa863d874717210b9fe10536c824afe1790eec247ded5b27d",
+    ("arm64", "bookworm", "core"): "e7548e8a82929722e973629ecc40fcfa886894cef3db88f23535149e7f730dc9",
+    ("amd64", "bookworm", "imapd"): "8d8dc6fc00bbb6cdb25d345844f41ce2f1c53f764b79a838eb2a03103eebfa86",
+    ("arm64", "bookworm", "imapd"): "178fa877ddd5df9930e8308b518f4b07df10e759050725f8217a0c1fb3fd707f",
+    ("amd64", "bookworm", "lmtpd"): "2f69ba5e35363de50962d42cccbfe4ed8495265044e244007d7ccddad77513ab",
+    ("arm64", "bookworm", "lmtpd"): "89f52fb36524f5877a177dff4a713ba771fd3f91f22ed0af7238d495e143b38f",
+    ("amd64", "trixie", "core"): "406d3781ed81e0913c472077dcf62cb1106e3855983efa6e44ddf43b4b0c9be1",
+    ("arm64", "trixie", "core"): "c75b0d9df11a77d07ebd8522920380c167fa47330ddefebe10575d99d0ecdf7f",
+    ("amd64", "trixie", "imapd"): "8d8dc6fc00bbb6cdb25d345844f41ce2f1c53f764b79a838eb2a03103eebfa86",
+    ("arm64", "trixie", "imapd"): "178fa877ddd5df9930e8308b518f4b07df10e759050725f8217a0c1fb3fd707f",
+    ("amd64", "trixie", "lmtpd"): "2f69ba5e35363de50962d42cccbfe4ed8495265044e244007d7ccddad77513ab",
+    ("arm64", "trixie", "lmtpd"): "89f52fb36524f5877a177dff4a713ba771fd3f91f22ed0af7238d495e143b38f",
 }
 
 
@@ -38,34 +43,32 @@ class DovecotDeployer(Deployer):
 
     def install(self):
         arch = host.get_fact(Arch)
+        codename = (host.get_fact(Command, "grep '^VERSION_CODENAME=' /etc/os-release | cut -d= -f2") or "").strip()
+        if codename not in {key[1] for key in DOVECOT_SHA256}:
+            raise ValueError(f"Unsupported Debian codename: {codename!r}")
         with blocked_service_startup():
             debs = []
             for pkg in ("core", "imapd", "lmtpd"):
-                deb, changed = _download_dovecot_package(pkg, arch)
+                deb, changed = _download_dovecot_package(pkg, arch, codename)
                 self.need_restart |= changed
                 if deb:
                     debs.append(deb)
             if debs:
                 deb_list = " ".join(debs)
-                # First dpkg may fail on missing dependencies (stderr suppressed);
-                # apt-get --fix-broken pulls them in, then dpkg retries cleanly.
+                # apt-get install with local .deb paths resolves depends
+                # against the configured repos (e.g. pulls libwrap0),
+                # The pin file written earlier by ChatmailDeployer prevents apt
+                # from installing a 'wrong' version
                 server.shell(
                     name="Install dovecot packages",
                     commands=[
-                        f"dpkg --force-confdef --force-confold -i {deb_list} 2> /dev/null || true",
-                        "DEBIAN_FRONTEND=noninteractive apt-get -y --fix-broken install",
-                        f"dpkg --force-confdef --force-confold -i {deb_list}",
+                        "DEBIAN_FRONTEND=noninteractive apt-get install -y "
+                        '-o Dpkg::Options::="--force-confdef" '
+                        '-o Dpkg::Options::="--force-confold" '
+                        f"--allow-downgrades {deb_list}",
                     ],
                 )
                 self.need_restart = True
-        self.put_file(
-            src=io.StringIO(
-                "Package: dovecot-*\n"
-                "Pin: version *\n"
-                "Pin-Priority: -1\n"
-            ),
-            dest="/etc/apt/preferences.d/pin-dovecot",
-        )
 
     def configure(self):
         configure_remote_units(self, self.config.mail_domain_bare, self.units)
@@ -78,7 +81,7 @@ class DovecotDeployer(Deployer):
         if not self.disable_mail and not self.need_restart:
             stale = host.get_fact(
                 Command,
-                'pid=$(systemctl show -p MainPID --value dovecot.service 2>/dev/null);'
+                "pid=$(systemctl show -p MainPID --value dovecot.service 2>/dev/null);"
                 ' [ "${pid:-0}" != "0" ] && readlink "/proc/$pid/exe" 2>/dev/null | grep -q "(deleted)"'
                 " && echo STALE || true",
             )
@@ -102,13 +105,13 @@ def _pick_url(primary, fallback):
         return fallback
 
 
-def _download_dovecot_package(package: str, arch: str) -> tuple[str | None, bool]:
+def _download_dovecot_package(package: str, arch: str, codename: str) -> tuple[str | None, bool]:
     """Download a dovecot .deb if needed, return (path, changed)."""
     arch = "amd64" if arch == "x86_64" else arch
     arch = "arm64" if arch == "aarch64" else arch
 
     pkg_name = f"dovecot-{package}"
-    sha256 = DOVECOT_SHA256.get((package, arch))
+    sha256 = DOVECOT_SHA256.get((arch, codename, package))
     if sha256 is None:
         op = apt.packages(packages=[pkg_name])
         return None, bool(getattr(op, "changed", False))
@@ -119,8 +122,10 @@ def _download_dovecot_package(package: str, arch: str) -> tuple[str | None, bool
 
     url_version = DOVECOT_ARCHIVE_VERSION.replace("+", "%2B")
     deb_base = f"{pkg_name}_{url_version}_{arch}.deb"
-    primary_url = f"https://download.delta.chat/dovecot/{deb_base}"
-    fallback_url = f"https://github.com/chatmail/dovecot/releases/download/upstream%2F{url_version}/{deb_base}"
+    primary_url = f"https://download.delta.chat/dovecot/{codename}/{url_version}/{deb_base}"
+    upstream_version = DOVECOT_ARCHIVE_VERSION.rsplit("-", 1)[0].replace("+", "%2B")
+    fallback_deb = f"{pkg_name}_{url_version}_{arch}_{codename}.deb"
+    fallback_url = f"https://github.com/chatmail/dovecot/releases/download/upstream%2F{upstream_version}/{fallback_deb}"
     url = _pick_url(primary_url, fallback_url)
     deb_filename = f"/root/{deb_base}"
 
@@ -134,6 +139,7 @@ def _download_dovecot_package(package: str, arch: str) -> tuple[str | None, bool
 
     return deb_filename, True
 
+
 def _configure_dovecot(deployer, config: Config, debug: bool = False):
     """Configures Dovecot IMAP server."""
     deployer.put_template(
@@ -144,9 +150,7 @@ def _configure_dovecot(deployer, config: Config, debug: bool = False):
         disable_ipv6=config.disable_ipv6,
     )
     deployer.put_file("dovecot/auth.conf", "/etc/dovecot/auth.conf")
-    deployer.put_file(
-        "dovecot/push_notification.lua", "/etc/dovecot/push_notification.lua"
-    )
+    deployer.put_file("dovecot/push_notification.lua", "/etc/dovecot/push_notification.lua")
 
     # as per https://doc.dovecot.org/2.3/configuration_manual/os/
     # it is recommended to set the following inotify limits

cmdeploy/src/cmdeploy/postfix/lmtp_header_cleanup

@@ -1,23 +1,3 @@
-# List of headers for incoming messages 
-# that must be retained for functionality and compatibility reasons 
-/^From:/            DUNNO
-/^Message-Id:/      DUNNO
-/^Chat-/            DUNNO
-/^Content-Type:/    DUNNO
-
-# For receiving clear-text messages (still supported in May 2026)
-/^Subject:/         DUNNO
-/^Date:/            DUNNO
-/^To:/              DUNNO
-/^CC:/              DUNNO
-/^References:/      DUNNO
-/^In-Reply-To:/     DUNNO
-
-# Senders might support Autocrypt 1 but not RFC9788 (Header Protection) 
-/^Autocrypt:/       DUNNO
-
-# SecureJoin V2 protocol headers (for backward compatibility) 
-/^Secure-Join/      DUNNO
-
-# Ignore all other headers
-/.*/                IGNORE
+/^DKIM-Signature:/            IGNORE
+/^Authentication-Results:/            IGNORE
+/^Received:/            IGNORE

cmdeploy/src/cmdeploy/tests/plugin.py

@@ -10,13 +10,11 @@ from pathlib import Path
 
 import pytest
 from chatmaild.config import is_valid_ipv4, read_config
-from domain_validator import DomainValidator
 
 
 def format_mail_domain(raw_domain: str) -> str:
     if is_valid_ipv4(raw_domain):
         return f"[{raw_domain}]"
-    DomainValidator().validate_domain_re(raw_domain)
     return raw_domain
 
 
@@ -62,8 +60,8 @@ def maildomain(chatmail_config):
 
 
 @pytest.fixture(scope="session")
-def sshdomain(chatmail_config):
-    return os.environ.get("CHATMAIL_SSH", chatmail_config.ssh_host)
+def sshdomain(maildomain):
+    return os.environ.get("CHATMAIL_SSH", maildomain)
 
 
 @pytest.fixture

cmdeploy/src/cmdeploy/tests/test_dovecot_deployer.py

@@ -3,6 +3,7 @@ from types import SimpleNamespace
 
 import pytest
 from pyinfra.facts.deb import DebPackages
+from pyinfra.facts.server import Command
 
 from cmdeploy.dovecot import deployer as dovecot_deployer
 
@@ -19,7 +20,7 @@ def make_host(*fact_pairs):
     """
     facts = dict(fact_pairs)
 
-    def get_fact(cls):
+    def get_fact(cls, *args):
         if cls not in facts:
             registered = ", ".join(c.__name__ for c in facts)
             raise LookupError(
@@ -82,7 +83,9 @@ def test_download_dovecot_package_skips_epoch_matched_install(monkeypatch):
         lambda **kwargs: downloads.append(kwargs),
     )
 
-    deb, changed = dovecot_deployer._download_dovecot_package("core", "amd64")
+    deb, changed = dovecot_deployer._download_dovecot_package(
+        "core", "amd64", codename="bookworm"
+    )
 
     assert deb is None, f"expected no deb path when version matches, got {deb!r}"
     assert changed is False, "should not flag changed when version already installed"
@@ -109,7 +112,9 @@ def test_download_dovecot_package_uses_archive_version_for_url_and_filename(
         lambda **kwargs: downloads.append(kwargs),
     )
 
-    deb, changed = dovecot_deployer._download_dovecot_package("core", "amd64")
+    deb, changed = dovecot_deployer._download_dovecot_package(
+        "core", "amd64", codename="bookworm"
+    )
 
     archive_version = dovecot_deployer.DOVECOT_ARCHIVE_VERSION.replace("+", "%2B")
     expected_deb = f"/root/dovecot-core_{archive_version}_amd64.deb"
@@ -139,6 +144,7 @@ def test_install_skips_dpkg_path_when_epoch_matched_packages_present(
                 },
             ),
             (dovecot_deployer.Arch, "x86_64"),
+            (Command, "bookworm"),
         ),
     )
     downloads = []
@@ -160,11 +166,13 @@ def test_install_skips_dpkg_path_when_epoch_matched_packages_present(
 def test_install_unsupported_arch_falls_back_to_apt(
     deployer, patch_blocked, mock_files_put, track_shell, monkeypatch
 ):
-    # For unsupported architectures, all fact lookups return the arch string.
     monkeypatch.setattr(
         dovecot_deployer,
         "host",
-        SimpleNamespace(get_fact=lambda cls: "riscv64"),
+        make_host(
+            (dovecot_deployer.Arch, "riscv64"),
+            (Command, "bookworm"),
+        ),
     )
     apt_calls = []
 
@@ -198,6 +206,7 @@ def test_install_runs_dpkg_when_packages_need_download(
         make_host(
             (dovecot_deployer.DebPackages, {}),
             (dovecot_deployer.Arch, "x86_64"),
+            (Command, "bookworm"),
         ),
     )
     monkeypatch.setattr(
@@ -217,10 +226,12 @@ def test_install_runs_dpkg_when_packages_need_download(
         f"expected one server.shell() call for dpkg install, got {len(track_shell)}"
     )
     cmds = track_shell[0]["commands"]
-    assert len(cmds) == 3, f"expected 3 dpkg/apt commands, got: {cmds}"
-    assert cmds[0].startswith("dpkg --force-confdef --force-confold -i ")
-    assert "apt-get -y --fix-broken install" in cmds[1]
-    assert cmds[2].startswith("dpkg --force-confdef --force-confold -i ")
+    assert len(cmds) == 1, f"expected single apt-get install command, got: {cmds}"
+    assert "apt-get install -y" in cmds[0]
+    assert '-o Dpkg::Options::="--force-confdef"' in cmds[0]
+    assert '-o Dpkg::Options::="--force-confold"' in cmds[0]
+    assert "--allow-downgrades" in cmds[0]
+    assert ".deb" in cmds[0]
     assert deployer.need_restart is True, (
         "need_restart should be True after dpkg install"
     )
@@ -235,3 +246,19 @@ def test_pick_url_falls_back_on_primary_error(monkeypatch):
     assert result == "http://fallback", (
         f"should fall back when primary fails, got {result!r}"
     )
+
+
+def test_install_fails_on_unsupported_debian_version(
+    deployer, patch_blocked, monkeypatch
+):
+    monkeypatch.setattr(
+        dovecot_deployer,
+        "host",
+        make_host(
+            (dovecot_deployer.Arch, "x86_64"),
+            (Command, "sid"),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="Unsupported Debian codename"):
+        deployer.install()

doc/source/getting_started.rst

@@ -14,14 +14,21 @@ Minimal requirements and prerequisites
 
 You will need the following:
 
--  Control over a domain through a DNS provider of your choice.
-   (there is experimental support for :ref:`IP-only relays <iponly>`).
-
--  A Debian 12 server with reachable SMTP/SUBMISSIONS/IMAPS/HTTPS ports.
+-  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>`_)
+
+-  Control over a domain through a DNS provider of your choice
+   (there is experimental support for :ref:`IP-only relays <iponly>`).
+
 
 .. _setup:
 
@@ -31,7 +38,7 @@ 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 relay.
+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.
@@ -51,25 +58,22 @@ steps. Please substitute it with your own domain.
       The ``mta-sts`` CNAME and ``_mta-sts`` TXT records
       are not needed for such domains.
 
-2. Login to the server with SSH, clone the repository and bootstrap the Python
+2. On your local PC, clone the repository and bootstrap the Python
    virtualenv.
 
    ::
 
-       ssh root@chat.example.org
        git clone https://github.com/chatmail/relay
        cd relay
        scripts/initenv.sh
 
-3. Then, create a chatmail configuration file
+3. On your local build machine (PC), create a chatmail configuration file
    ``chatmail.ini``:
 
    ::
 
        scripts/cmdeploy init chat.example.org  # <-- use your domain
 
-   .. note::
-
    To use self-signed TLS certificates
    instead of Let's Encrypt,
    use a domain name starting with ``_``
@@ -80,7 +84,13 @@ steps. Please substitute it with your own domain.
    See the :doc:`overview`
    for details on certificate provisioning.
 
-4. Now run the deployment script to install the relay to the server:
+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:
 
    ::
 
@@ -92,6 +102,7 @@ steps. Please substitute it with your own domain.
    public).
 
 
+
 Docker installation
 -------------------
 
@@ -99,32 +110,26 @@ There is experimental support for running chatmail via Docker.
 A monolithic image based on the above cmdeploy method is available `through a separate repository <https://github.com/chatmail/docker/pkgs/container/docker>`_.
 See the `chatmail/docker README <https://github.com/chatmail/docker>`_ for full setup instructions.
 
-
-Next Steps
-----------
-
-Now you should display and check all recommended DNS records
-to enable federation with other relays:
-
-::
-
-   scripts/cmdeploy dns
-
-You should also test whether your chatmail service is working correctly:
-
-::
-
-   scripts/cmdeploy test
-
-Other Helpful Commands
+Other helpful commands
 ----------------------
 
-To check the status of your chatmail relay:
+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:
 
@@ -166,9 +171,8 @@ This starts a local live development cycle for chatmail web pages:
    directory and generating HTML files and copying assets to the
    ``www/build`` directory.
 
--  if you are running scripts/cmdeploy webdev on the relay itself,
-   you need to configure a route in /etc/nginx/nginx.conf
-   to expose the build directory.
+-  Starts a browser window automatically where you can “refresh” as
+   needed.
 
 Custom web pages
 ----------------
@@ -186,7 +190,7 @@ 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 relay and run:
+creating addresses, login with ssh to the deployment machine and run:
 
 ::
 
@@ -242,3 +246,25 @@ The deploy will verify that both files exist on the server.
    If you use such a setup, you must trigger the reload explicitly after renewal::
 
       systemctl start tls-cert-reload.service
+
+
+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.

doc/source/migrate.rst

@@ -1,6 +1,6 @@
 
-Migrating the relay to a new server
-===================================
+Migrating to a new machine
+===========================
 
 This migration tutorial provides a step-wise approach
 to safely migrate a chatmail relay from one remote machine to another.
@@ -96,17 +96,3 @@ in this case, just run ``ssh-keygen -R "mail.example.org"`` as recommended.
    If you have lowered the Time-to-Live for DNS records in step 1,
    better use a higher value again (between 14400 and 86400 seconds) once you are sure everything works.
 
-
-Migrating a local chatmail/relay repository to the server
-=========================================================
-
-To move the directory with your local chatmail/relay repository and ``chatmail.ini`` file,
-clone the `relay repository <https://github.com/chatmail/relay/>` to the server where the relay is running,
-and copy the ``chatmail.ini`` file from your local chatmail/relay repository there.
-
-If you made local changes to the repository,
-you can store them in a file with ``git diff origin/main > local-changes.patch``,
-copy the file to the repository on the server,
-and run ``git apply local-changes.patch``.
-
-Then you can proceed with the `installation steps <setup>`.