feat: [#315] Step 3.2 & 3.3 - Crontab installation and wiring

This completes Steps 3.2 and 3.3 of Phase 3:

Step 3.2: Add crontab installation playbook
- Created install-backup-crontab.yml Ansible playbook
- Copies maintenance-backup.sh to /usr/local/bin/ (mode 0755, root:root)
- Installs crontab entry to /etc/cron.d/tracker-backup (mode 0644, root:root)
- Creates /var/log/tracker-backup.log (mode 0644, root:root)
- Registered in ProjectGenerator

Step 3.3: Wire crontab into Release command
- Created InstallBackupCrontabStep system step module
- Added to backup release workflow (after config deployment)
- Conditional execution (only if backup enabled in environment)
- Updated ReleaseStep enum with InstallBackupCrontab variant
- Added comprehensive error variant with help text

Integration:
- Release workflow: Create Storage → Deploy Config → Install Crontab → Render Compose → Deploy Compose
- All services remain healthy during backup operations
- Crontab isolated from Docker Compose setup via profiles

Author: josecelano

src/application/command_handlers/release/errors.rs

@@ -146,6 +146,18 @@ pub enum ReleaseCommandHandlerError {
         step: ReleaseStep,
     },
 
+    /// Backup crontab installation failed
+    #[error("Backup crontab installation failed: {message}")]
+    InstallBackupCrontabFailed {
+        /// Description of the failure
+        message: String,
+        /// The underlying error from the installation step
+        #[source]
+        source: BoxedStepError,
+        /// The release step that failed
+        step: ReleaseStep,
+    },
+
     /// Backup storage directory creation failed
     #[error("Backup storage creation failed: {message}")]
     CreateBackupStorageFailed {
@@ -262,6 +274,11 @@ impl Traceable for ReleaseCommandHandlerError {
             Self::DeployBackupConfigFailed { message, .. } => {
                 format!("ReleaseCommandHandlerError: Backup configuration deployment failed - {message}")
             }
+            Self::InstallBackupCrontabFailed { message, .. } => {
+                format!(
+                    "ReleaseCommandHandlerError: Backup crontab installation failed - {message}"
+                )
+            }
             Self::CaddyConfigDeployment { message, .. } => {
                 format!(
                     "ReleaseCommandHandlerError: Caddy configuration deployment failed - {message}"
@@ -311,6 +328,7 @@ impl Traceable for ReleaseCommandHandlerError {
             | Self::RenderBackupTemplatesFailed { .. }
             | Self::CreateBackupStorageFailed { .. }
             | Self::DeployBackupConfigFailed { .. }
+            | Self::InstallBackupCrontabFailed { .. }
             | Self::CaddyConfigDeployment { .. }
             | Self::TrackerConfigDeployment { .. }
             | Self::GrafanaProvisioningDeployment { .. }
@@ -335,6 +353,7 @@ impl Traceable for ReleaseCommandHandlerError {
             | Self::RenderBackupTemplatesFailed { .. }
             | Self::CreateBackupStorageFailed { .. }
             | Self::DeployBackupConfigFailed { .. }
+            | Self::InstallBackupCrontabFailed { .. }
             | Self::CaddyConfigDeployment { .. }
             | Self::TrackerConfigDeployment { .. }
             | Self::GrafanaProvisioningDeployment { .. }
@@ -622,6 +641,37 @@ For more information, see docs/user-guide/commands.md"
 
 4. Check file permissions on remote host
 5. Review Ansible playbook execution logs above"
+            }
+            Self::InstallBackupCrontabFailed { .. } => {
+                "Backup Crontab Installation Failed - Troubleshooting:
+
+1. Verify SSH connection to remote host:
+   ssh <user>@<host>
+
+2. Check Ansible playbook exists:
+   ls templates/ansible/install-backup-crontab.yml
+
+3. Verify maintenance script is in build directory:
+   ls build/<env-name>/backup/etc/maintenance-backup.sh
+
+4. Verify crontab entry is generated:
+   ls build/<env-name>/backup/etc/maintenance-backup.cron
+
+5. Check that cron daemon is running on target:
+   ssh <user>@<host> 'systemctl status cron'
+
+6. Check file permissions and ownership on target:
+   ssh <user>@<host> 'ls -la /usr/local/bin/maintenance-backup.sh'
+   ssh <user>@<host> 'ls -la /etc/cron.d/tracker-backup'
+
+Common causes:
+- Cron daemon not installed or running
+- Permission denied on cron directory
+- Insufficient disk space on target
+- SSH authentication failure
+- Ansible playbook not found
+
+For more information, see docs/user-guide/commands.md"
             }
             Self::CaddyConfigDeployment { .. } => {
                 "Caddy Configuration Deployment Failed - Troubleshooting:

src/application/command_handlers/release/steps/backup.rs

@@ -13,6 +13,7 @@ use crate::application::command_handlers::common::StepResult;
 use crate::application::command_handlers::release::errors::ReleaseCommandHandlerError;
 use crate::application::steps::application::{CreateBackupStorageStep, DeployBackupConfigStep};
 use crate::application::steps::rendering::RenderBackupTemplatesStep;
+use crate::application::steps::system::InstallBackupCrontabStep;
 use crate::domain::environment::state::ReleaseStep;
 use crate::domain::environment::{Environment, Releasing};
 use crate::domain::template::TemplateManager;
@@ -50,6 +51,7 @@ pub async fn release(
     render_templates(environment).await?;
     create_storage(environment)?;
     deploy_config_to_remote(environment)?;
+    install_crontab(environment)?;
 
     Ok(())
 }
@@ -157,3 +159,39 @@ fn deploy_config_to_remote(
 
     Ok(())
 }
+
+/// Install backup crontab and maintenance script on the remote host
+///
+/// This installs the cron job that will execute backups on the configured schedule.
+/// The cron daemon is always running, so the job will automatically execute on schedule.
+///
+/// # Errors
+///
+/// Returns a tuple of (error, `ReleaseStep::InstallBackupCrontab`) if installation fails
+#[allow(clippy::result_large_err)]
+fn install_crontab(
+    environment: &Environment<Releasing>,
+) -> StepResult<(), ReleaseCommandHandlerError, ReleaseStep> {
+    let current_step = ReleaseStep::InstallBackupCrontab;
+
+    InstallBackupCrontabStep::new(ansible_client(environment))
+        .execute()
+        .map_err(|e| {
+            (
+                ReleaseCommandHandlerError::InstallBackupCrontabFailed {
+                    message: e.to_string(),
+                    source: Box::new(e),
+                    step: current_step,
+                },
+                current_step,
+            )
+        })?;
+
+    info!(
+        command = "release",
+        step = %current_step,
+        "Backup crontab and maintenance script installed successfully"
+    );
+
+    Ok(())
+}

src/application/steps/mod.rs

@@ -38,7 +38,10 @@ pub use rendering::{
     RenderDockerComposeTemplatesStep, RenderOpenTofuTemplatesStep,
 };
 pub use software::{InstallDockerComposeStep, InstallDockerStep};
-pub use system::{ConfigureFirewallStep, ConfigureSecurityUpdatesStep, WaitForCloudInitStep};
+pub use system::{
+    ConfigureFirewallStep, ConfigureSecurityUpdatesStep, InstallBackupCrontabStep,
+    WaitForCloudInitStep,
+};
 pub use validation::{
     ValidateCloudInitCompletionStep, ValidateDockerComposeInstallationStep,
     ValidateDockerInstallationStep,

src/application/steps/system/install_backup_crontab.rs

@@ -0,0 +1,101 @@
+//! Backup crontab installation step
+//!
+//! This module provides the `InstallBackupCrontabStep` which handles installation
+//! of the backup crontab entry and maintenance script on remote hosts via Ansible playbooks.
+//! This step ensures that scheduled backups are configured to run automatically.
+//!
+//! ## Key Features
+//!
+//! - Copies maintenance-backup.sh to /usr/local/bin/ with executable permissions
+//! - Installs crontab entry to /etc/cron.d/tracker-backup
+//! - Creates backup log file with proper permissions
+//! - Verifies all files are properly installed
+//!
+//! ## Configuration Process
+//!
+//! The step executes the "install-backup-crontab" Ansible playbook which handles:
+//! - Copying the maintenance script to /usr/local/bin/
+//! - Installing the crontab entry to /etc/cron.d/
+//! - Creating the backup log file
+//! - Verifying all files exist and have correct permissions
+
+use std::sync::Arc;
+use tracing::{info, instrument};
+
+use crate::adapters::ansible::AnsibleClient;
+use crate::shared::command::CommandError;
+
+/// Step that installs backup crontab and maintenance script via Ansible
+///
+/// This step installs the backup crontab entry and the maintenance script
+/// that will orchestrate scheduled backups. The crontab entry runs on the
+/// configured schedule to stop the tracker, perform backup, and restart.
+pub struct InstallBackupCrontabStep {
+    ansible_client: Arc<AnsibleClient>,
+}
+
+impl InstallBackupCrontabStep {
+    /// Create a new backup crontab installation step
+    ///
+    /// # Arguments
+    ///
+    /// * `ansible_client` - Ansible client for running playbooks
+    #[must_use]
+    pub fn new(ansible_client: Arc<AnsibleClient>) -> Self {
+        Self { ansible_client }
+    }
+
+    /// Execute the backup crontab installation
+    ///
+    /// # Errors
+    ///
+    /// Returns `CommandError` if:
+    /// - Ansible playbook execution fails
+    /// - Files cannot be copied to remote host
+    /// - Permissions cannot be set correctly
+    /// - Verification checks fail
+    #[instrument(
+        name = "install_backup_crontab",
+        skip_all,
+        fields(step_type = "system", component = "backup", method = "ansible")
+    )]
+    pub fn execute(&self) -> Result<(), CommandError> {
+        info!(
+            step = "install_backup_crontab",
+            action = "install_crontab",
+            "Installing backup crontab and maintenance script"
+        );
+
+        match self
+            .ansible_client
+            .run_playbook("install-backup-crontab", &[])
+        {
+            Ok(_) => {
+                info!(
+                    step = "install_backup_crontab",
+                    action = "install_crontab",
+                    status = "completed",
+                    "Backup crontab and script installed successfully"
+                );
+                Ok(())
+            }
+            Err(e) => Err(e),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::adapters::ansible::AnsibleClient;
+    use std::path::PathBuf;
+    use std::sync::Arc;
+
+    #[test]
+    fn it_should_create_step_with_ansible_client() {
+        let build_dir = PathBuf::from("/tmp/test-build");
+        let ansible_client = Arc::new(AnsibleClient::new(build_dir));
+        let step = InstallBackupCrontabStep::new(ansible_client);
+        assert!(Arc::strong_count(&step.ansible_client) >= 1);
+    }
+}

src/application/steps/system/mod.rs

@@ -8,6 +8,7 @@
  * - Cloud-init completion waiting
  * - Automatic security updates configuration
  * - UFW firewall configuration (SSH access only)
+ * - Backup crontab installation
  *
  * Note: Tracker service ports are controlled via Docker port bindings in docker-compose,
  * not through UFW rules. Docker bypasses UFW for published container ports.
@@ -21,8 +22,10 @@
 
 pub mod configure_firewall;
 pub mod configure_security_updates;
+pub mod install_backup_crontab;
 pub mod wait_cloud_init;
 
 pub use configure_firewall::ConfigureFirewallStep;
 pub use configure_security_updates::ConfigureSecurityUpdatesStep;
+pub use install_backup_crontab::InstallBackupCrontabStep;
 pub use wait_cloud_init::WaitForCloudInitStep;

src/domain/environment/state/release_failed.rs

@@ -58,6 +58,8 @@ pub enum ReleaseStep {
     CreateBackupStorage,
     /// Deploying Backup configuration to the remote host via Ansible (if backup enabled)
     DeployBackupConfigToRemote,
+    /// Installing backup crontab and maintenance script (if backup enabled)
+    InstallBackupCrontab,
     /// Rendering Caddy configuration templates to the build directory (if HTTPS enabled)
     RenderCaddyTemplates,
     /// Deploying Caddy configuration to the remote host via Ansible (if HTTPS enabled)
@@ -85,6 +87,7 @@ impl fmt::Display for ReleaseStep {
             Self::RenderBackupTemplates => "Render Backup Templates",
             Self::CreateBackupStorage => "Create Backup Storage",
             Self::DeployBackupConfigToRemote => "Deploy Backup Config to Remote",
+            Self::InstallBackupCrontab => "Install Backup Crontab",
             Self::RenderCaddyTemplates => "Render Caddy Templates",
             Self::DeployCaddyConfigToRemote => "Deploy Caddy Config to Remote",
             Self::RenderDockerComposeTemplates => "Render Docker Compose Templates",

src/infrastructure/templating/ansible/template/renderer/project_generator.rs

@@ -316,6 +316,7 @@ impl AnsibleProjectGenerator {
             "create-mysql-storage.yml",
             "create-backup-storage.yml",
             "deploy-backup-config.yml",
+            "install-backup-crontab.yml",
             "deploy-caddy-config.yml",
             "deploy-compose-files.yml",
             "run-compose-services.yml",
@@ -326,7 +327,7 @@ impl AnsibleProjectGenerator {
 
         tracing::debug!(
             "Successfully copied {} static template files",
-            22 // ansible.cfg + 21 playbooks
+            23 // ansible.cfg + 22 playbooks
         );
 
         Ok(())