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 diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst index aba445bf1..6b1d6486a 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: :: @@ -102,7 +92,6 @@ steps. Please substitute it with your own domain. public). - Docker installation ------------------- @@ -110,26 +99,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: @@ -171,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 ---------------- @@ -190,7 +186,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: :: @@ -246,25 +242,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.