refactor: use put_file/put_template helpers across all deployers

Author: hpk42

cmdeploy/src/cmdeploy/basedeploy.py

@@ -99,6 +99,22 @@ def perform_stages(self, deployers):
 
 
 class Deployer:
+    """Base class for deployers that manage remote service configuration.
+
+    Deployers go through three stages: ``install``, ``configure``, and
+    ``activate``.  During ``configure``, use :meth:`put_file` and
+    :meth:`put_template` to upload files — they automatically set
+    ``need_restart = True`` when a file changes on the remote host.
+    The ``activate`` stage can then inspect ``need_restart`` to decide
+    whether to restart or reload the managed service.
+
+    Deployers with an ``enabled`` flag (default ``True``) support a
+    disabled mode: when ``enabled`` is ``False``, the ``put_*`` methods
+    remove the target file from the remote host instead of uploading it,
+    allowing clean un-deployment of optional components.
+    """
+
+    enabled = True
     need_restart = False
     daemon_reload = False
 
@@ -111,10 +127,15 @@ def configure(self):
     def activate(self):
         pass
 
-    def put_or_remove_file(
+    def put_file(
         self, *, name, dest, src=None, executable=False, owner="root"
     ):
-        """Upload a file or executable, or remove it if deployer is disabled."""
+        """Upload a file to *dest*, or remove it when the deployer is disabled.
+
+        Sets ``need_restart = True`` when the remote file changes.
+        When ``self.enabled`` is ``False``, the file at *dest* is removed
+        instead of uploaded.
+        """
         if self.enabled:
             mode = "755" if executable else "644"
             res = files.put(
@@ -127,10 +148,16 @@ def put_or_remove_file(
             self.need_restart = True
         return res
 
-    def put_or_remove_template(
+    def put_template(
         self, *, name, src, dest, owner="root", mode="644", **kwargs
     ):
-        """Upload a templated file or remove it if deployer is disabled."""
+        """Upload a Jinja2 template to *dest*, or remove it when disabled.
+
+        Sets ``need_restart = True`` when the rendered remote file changes.
+        When ``self.enabled`` is ``False``, the file at *dest* is removed
+        instead of uploaded.  Extra *kwargs* are passed to the template
+        as render context.
+        """
         if self.enabled:
             res = files.template(
                 name=name,

cmdeploy/src/cmdeploy/deployers.py

@@ -388,25 +388,16 @@ def install(self):
             self.need_restart = True
 
     def configure(self):
-        systemd_unit = files.put(
+        self.put_file(
             name="Upload iroh-relay systemd unit",
             src=get_resource("iroh-relay.service"),
             dest="/etc/systemd/system/iroh-relay.service",
-            user="root",
-            group="root",
-            mode="644",
         )
-        self.need_restart |= systemd_unit.changed
-
-        iroh_config = files.put(
+        self.put_file(
             name="Upload iroh-relay config",
             src=get_resource("iroh-relay.toml"),
             dest="/etc/iroh-relay.toml",
-            user="root",
-            group="root",
-            mode="644",
         )
-        self.need_restart |= iroh_config.changed
 
     def activate(self):
         systemd.service(
@@ -421,15 +412,11 @@ def activate(self):
 
 class JournaldDeployer(Deployer):
     def configure(self):
-        journald_conf = files.put(
+        self.put_file(
             name="Configure journald",
             src=get_resource("journald.conf"),
             dest="/etc/systemd/journald.conf",
-            user="root",
-            group="root",
-            mode="644",
         )
-        self.need_restart = journald_conf.changed
 
     def activate(self):
         systemd.service(

cmdeploy/src/cmdeploy/dovecot/deployer.py

@@ -29,7 +29,7 @@ def install(self):
 
     def configure(self):
         configure_remote_units(self.config.mail_domain, self.units)
-        self.need_restart, self.daemon_reload = _configure_dovecot(self.config)
+        self.need_restart, self.daemon_reload = _configure_dovecot(self, self.config)
 
     def activate(self):
         activate_remote_units(self.units)
@@ -81,38 +81,30 @@ def _install_dovecot_package(package: str, arch: str):
     apt.deb(name=f"Install dovecot-{package}", src=deb_filename)
 
 
-def _configure_dovecot(config: Config, debug: bool = False) -> (bool, bool):
+
+def _configure_dovecot(deployer, config: Config, debug: bool = False) -> (bool, bool):
     """Configures Dovecot IMAP server."""
-    need_restart = False
+    deployer.need_restart = False
     daemon_reload = False
 
-    main_config = files.template(
+    deployer.put_template(
+        name="Upload dovecot.conf",
         src=get_resource("dovecot/dovecot.conf.j2"),
         dest="/etc/dovecot/dovecot.conf",
-        user="root",
-        group="root",
-        mode="644",
         config=config,
         debug=debug,
         disable_ipv6=config.disable_ipv6,
     )
-    need_restart |= main_config.changed
-    auth_config = files.put(
+    deployer.put_file(
+        name="Upload auth.conf",
         src=get_resource("dovecot/auth.conf"),
         dest="/etc/dovecot/auth.conf",
-        user="root",
-        group="root",
-        mode="644",
     )
-    need_restart |= auth_config.changed
-    lua_push_notification_script = files.put(
+    deployer.put_file(
+        name="Upload push_notification.lua",
         src=get_resource("dovecot/push_notification.lua"),
         dest="/etc/dovecot/push_notification.lua",
-        user="root",
-        group="root",
-        mode="644",
     )
-    need_restart |= lua_push_notification_script.changed
 
     # as per https://doc.dovecot.org/2.3/configuration_manual/os/
     # it is recommended to set the following inotify limits
@@ -134,7 +126,7 @@ def _configure_dovecot(config: Config, debug: bool = False) -> (bool, bool):
         path="/etc/environment",
         line="TZ=:/etc/localtime",
     )
-    need_restart |= timezone_env.changed
+    deployer.need_restart |= timezone_env.changed
 
     restart_conf = files.put(
         name="dovecot: restart automatically on failure",
@@ -144,10 +136,10 @@ def _configure_dovecot(config: Config, debug: bool = False) -> (bool, bool):
     daemon_reload |= restart_conf.changed
 
     # Validate dovecot configuration before restart
-    if need_restart:
+    if deployer.need_restart:
         server.shell(
             name="Validate dovecot configuration",
             commands=["doveconf -n >/dev/null"],
         )
 
-    return need_restart, daemon_reload
+    return deployer.need_restart, daemon_reload

cmdeploy/src/cmdeploy/filtermail/deployer.py

@@ -29,15 +29,13 @@ def install(self):
 
     def configure(self):
         for service in self.services:
-            self.need_restart |= files.template(
+            self.put_template(
+                name=f"Upload {service}.service",
                 src=get_resource(f"filtermail/{service}.service.j2"),
                 dest=f"/etc/systemd/system/{service}.service",
-                user="root",
-                group="root",
-                mode="644",
                 bin_path=self.bin_path,
                 config_path=self.config_path,
-            ).changed
+            )
 
     def activate(self):
         for service in self.services:

cmdeploy/src/cmdeploy/mtail/deployer.py

@@ -1,5 +1,5 @@
 from pyinfra import facts, host
-from pyinfra.operations import apt, files, server, systemd
+from pyinfra.operations import apt, server, systemd
 
 from cmdeploy.basedeploy import (
     Deployer,
@@ -37,25 +37,18 @@ def install(self):
     def configure(self):
         # Using our own systemd unit instead of `/usr/lib/systemd/system/mtail.service`.
         # This allows to read from journalctl instead of log files.
-        files.template(
+        self.put_template(
+            name="Upload mtail.service",
             src=get_resource("mtail/mtail.service.j2"),
             dest="/etc/systemd/system/mtail.service",
-            user="root",
-            group="root",
-            mode="644",
             address=self.mtail_address or "127.0.0.1",
             port=3903,
         )
-
-        mtail_conf = files.put(
+        self.put_file(
             name="Mtail configuration",
             src=get_resource("mtail/delivered_mail.mtail"),
             dest="/etc/mtail/delivered_mail.mtail",
-            user="root",
-            group="root",
-            mode="644",
         )
-        self.need_restart = mtail_conf.changed
 
     def activate(self):
         systemd.service(

cmdeploy/src/cmdeploy/nginx/deployer.py

@@ -47,7 +47,7 @@ def install(self):
         files.file("/usr/sbin/policy-rc.d", present=False)
 
     def configure(self):
-        self.need_restart = _configure_nginx(self.config)
+        _configure_nginx(self, self.config)
 
     def activate(self):
         systemd.service(
@@ -60,40 +60,31 @@ def activate(self):
         self.need_restart = False
 
 
-def _configure_nginx(config: Config, debug: bool = False) -> bool:
+def _configure_nginx(deployer, config: Config, debug: bool = False):
     """Configures nginx HTTP server."""
-    need_restart = False
+    deployer.need_restart = False
 
-    main_config = files.template(
+    deployer.put_template(
+        name="Upload nginx.conf",
         src=get_resource("nginx/nginx.conf.j2"),
         dest="/etc/nginx/nginx.conf",
-        user="root",
-        group="root",
-        mode="644",
         config=config,
         disable_ipv6=config.disable_ipv6,
     )
-    need_restart |= main_config.changed
 
-    autoconfig = files.template(
+    deployer.put_template(
+        name="Upload autoconfig.xml",
         src=get_resource("nginx/autoconfig.xml.j2"),
         dest="/var/www/html/.well-known/autoconfig/mail/config-v1.1.xml",
-        user="root",
-        group="root",
-        mode="644",
         config=config,
     )
-    need_restart |= autoconfig.changed
 
-    mta_sts_config = files.template(
+    deployer.put_template(
+        name="Upload mta-sts.txt",
         src=get_resource("nginx/mta-sts.txt.j2"),
         dest="/var/www/html/.well-known/mta-sts.txt",
-        user="root",
-        group="root",
-        mode="644",
         config=config,
     )
-    need_restart |= mta_sts_config.changed
 
     # install CGI newemail script
     #
@@ -105,13 +96,9 @@ def _configure_nginx(config: Config, debug: bool = False) -> bool:
         group="root",
     )
 
-    files.put(
+    deployer.put_file(
         name="Upload cgi newemail.py script",
         src=get_resource("newemail.py", pkg="chatmaild").open("rb"),
         dest=f"{cgi_dir}/newemail.py",
-        user="root",
-        group="root",
-        mode="755",
+        executable=True,
     )
-
-    return need_restart