From ab3b9d156ab1af1ba86fa33bc319560726751edc Mon Sep 17 00:00:00 2001 From: missytake Date: Tue, 17 Feb 2026 20:33:16 +0100 Subject: [PATCH 1/4] cmdeploy: add ssh_host chatmail.ini option to deploy remotely --- chatmaild/src/chatmaild/config.py | 1 + chatmaild/src/chatmaild/ini/chatmail.ini.f | 3 +++ cmdeploy/src/cmdeploy/cmdeploy.py | 8 ++++---- cmdeploy/src/cmdeploy/tests/plugin.py | 4 ++-- 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/chatmaild/src/chatmaild/config.py b/chatmaild/src/chatmaild/config.py index db79d75db..34333e142 100644 --- a/chatmaild/src/chatmaild/config.py +++ b/chatmaild/src/chatmaild/config.py @@ -18,6 +18,7 @@ def __init__(self, inipath, params): self._inipath = inipath raw_domain = params["mail_domain"] self.mail_domain_bare = raw_domain + self.ssh_host = params.get("ssh_host", raw_domain) if is_valid_ipv4(raw_domain): self.ipv4_relay = raw_domain diff --git a/chatmaild/src/chatmaild/ini/chatmail.ini.f b/chatmaild/src/chatmaild/ini/chatmail.ini.f index 85bdb6d4c..78a89a90c 100644 --- a/chatmaild/src/chatmaild/ini/chatmail.ini.f +++ b/chatmaild/src/chatmaild/ini/chatmail.ini.f @@ -3,6 +3,9 @@ # 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 # diff --git a/cmdeploy/src/cmdeploy/cmdeploy.py b/cmdeploy/src/cmdeploy/cmdeploy.py index c4ea48152..f4fe83bc6 100644 --- a/cmdeploy/src/cmdeploy/cmdeploy.py +++ b/cmdeploy/src/cmdeploy/cmdeploy.py @@ -87,7 +87,7 @@ def run_cmd_options(parser): def run_cmd(args, out): """Deploy chatmail services on the remote server.""" - ssh_host = args.ssh_host if args.ssh_host else args.config.mail_domain_bare + ssh_host = args.ssh_host if args.ssh_host else args.config.ssh_host sshexec = get_sshexec(ssh_host) require_iroh = args.config.enable_iroh_relay strict_tls = args.config.tls_cert_mode == "acme" @@ -107,7 +107,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 == "localhost": + if ssh_host in ["localhost", "@local"]: cmd = f"{pyinf} @local {deploy_path} -y" if version.parse(pyinfra.__version__) < version.parse("3"): @@ -148,7 +148,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.mail_domain + ssh_host = args.ssh_host if args.ssh_host else args.config.ssh_host sshexec = get_sshexec(ssh_host, verbose=args.verbose) tls_cert_mode = args.config.tls_cert_mode strict_tls = tls_cert_mode == "acme" @@ -185,7 +185,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.mail_domain_bare + ssh_host = args.ssh_host if args.ssh_host else args.config.ssh_host sshexec = get_sshexec(ssh_host, verbose=args.verbose) out.green(f"chatmail domain: {args.config.mail_domain}") diff --git a/cmdeploy/src/cmdeploy/tests/plugin.py b/cmdeploy/src/cmdeploy/tests/plugin.py index c61b44264..969aea7d8 100644 --- a/cmdeploy/src/cmdeploy/tests/plugin.py +++ b/cmdeploy/src/cmdeploy/tests/plugin.py @@ -62,8 +62,8 @@ def maildomain(chatmail_config): @pytest.fixture(scope="session") -def sshdomain(maildomain): - return os.environ.get("CHATMAIL_SSH", maildomain) +def sshdomain(chatmail_config): + return os.environ.get("CHATMAIL_SSH", chatmail_config.ssh_host) @pytest.fixture From cf215f971d4b995aa6f0c0a9446bac61fc1d6779 Mon Sep 17 00:00:00 2001 From: missytake Date: Mon, 16 Feb 2026 15:57:25 +0100 Subject: [PATCH 2/4] docs: cmdeploy dns + test are kind of necessary --- doc/source/getting_started.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst index aba445bf1..7baf47092 100644 --- a/doc/source/getting_started.rst +++ b/doc/source/getting_started.rst @@ -102,7 +102,6 @@ steps. Please substitute it with your own domain. public). - Docker installation ------------------- @@ -110,26 +109,32 @@ There is experimental support for running chatmail via Docker. A monolithic image based on the above cmdeploy method is available `through a separate repository `_. See the `chatmail/docker README `_ for full setup instructions. -Other helpful commands ----------------------- -To check the status of your deployment server running the chatmail service: +Next Steps +---------- + +Now you should display and check all recommended DNS records +to enable federation with other relays: :: - scripts/cmdeploy status + scripts/cmdeploy dns -To display and check all recommended DNS records: +You should also test whether your chatmail service is working correctly: :: - scripts/cmdeploy dns + scripts/cmdeploy test + +Other Helpful Commands +---------------------- -To test whether your chatmail service is working correctly: +To check the status of your chatmail relay: :: - scripts/cmdeploy test + scripts/cmdeploy status + To measure the performance of your chatmail service: From 85eddb671e4893f585f2c159956e24371b3b9034 Mon Sep 17 00:00:00 2001 From: missytake Date: Mon, 16 Feb 2026 15:52:25 +0100 Subject: [PATCH 3/4] docs: use ssh_host = localhost in getting started docs remove mentions of the build machine / deployment server separation --- doc/source/getting_started.rst | 56 ++++++++-------------------------- 1 file changed, 12 insertions(+), 44 deletions(-) diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst index 7baf47092..2b068b27e 100644 --- a/doc/source/getting_started.rst +++ b/doc/source/getting_started.rst @@ -14,21 +14,14 @@ Minimal requirements and prerequisites You will need the following: -- A Debian 12 **deployment server** with reachable SMTP/SUBMISSIONS/IMAPS/HTTPS ports. +- Control over a domain through a DNS provider of your choice. + (there is experimental support for :ref:`IP-only relays `). + +- 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. -- 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 `_) - -- Control over a domain through a DNS provider of your choice - (there is experimental support for :ref:`IP-only relays `). - .. _setup: @@ -38,7 +31,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 deployment server. +1. Setup the initial DNS records for your relay. 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. @@ -58,22 +51,25 @@ steps. Please substitute it with your own domain. 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 +2. Login to the server with SSH, 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. On your local build machine (PC), create a chatmail configuration file +3. Then, 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 ``_`` @@ -84,13 +80,7 @@ steps. Please substitute it with your own domain. 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: +4. Now run the deployment script to install the relay to the server: :: @@ -195,7 +185,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 deployment machine and run: +creating addresses, login with ssh to the relay and run: :: @@ -251,25 +241,3 @@ 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. From c9c1f226b406e06ad69adc2101535d900bf20dee Mon Sep 17 00:00:00 2001 From: missytake Date: Mon, 16 Feb 2026 16:57:56 +0100 Subject: [PATCH 4/4] docs: webdev needs to be exposed via nginx if run on the relay --- doc/source/getting_started.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst index 2b068b27e..6b1d6486a 100644 --- a/doc/source/getting_started.rst +++ b/doc/source/getting_started.rst @@ -166,8 +166,9 @@ This starts a local live development cycle for chatmail web pages: directory and generating HTML files and copying assets to the ``www/build`` directory. -- Starts a browser window automatically where you can “refresh” as - needed. +- 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. Custom web pages ----------------