feat: [#21] Phase 3 - MySQL Database Backup Automation

[josecelano]

Summary

This PR implements automated MySQL database backup functionality as part of Phase 3 of Issue #21 (Complete Application Installation Automation). This phase focuses on backup automation, laying the foundation for subsequent SSL automation work.

🎯 What's Implemented

Core Backup Automation

• MySQL Backup Script (application/share/bin/mysql-backup.sh)
  • Full database backup with compression (gzip)
  • Configurable retention policy (default: 7 days)
  • Comprehensive logging with timestamps
  • Error handling and validation
  • Non-interactive operation for automation

Infrastructure Integration

• Deployment Integration in infrastructure/scripts/deploy-app.sh
  • setup_backup_automation() function
  • Automated cron job installation
  • Environment-aware configuration
  • Part of the standard deployment workflow

Configuration Management

• Environment Variables added to configuration templates
  • ENABLE_DB_BACKUPS (boolean) - Enable/disable backup automation
  • BACKUP_RETENTION_DAYS (integer) - Number of days to retain backups
• Default Settings - Backups enabled by default in local development
• Template Updates - All environment templates include backup variables

Documentation & Testing

• Comprehensive Testing Guide (docs/guides/database-backup-testing-guide.md)
  • Manual testing procedures
  • Validation steps for backup content
  • Troubleshooting guidance
• Updated Progress Documentation - Issue Phase 3: Complete Application Installation Automation #21 progress tracking updated

🧪 Testing Performed

Automated Testing

• ✅ CI Pipeline: All linting and unit tests pass
• ✅ Infrastructure Tests: Terraform validation, cloud-init syntax
• ✅ Application Tests: Docker Compose validation, script syntax

Manual Testing (Comprehensive)

• ✅ End-to-End Deployment: Full infrastructure + application deployment
• ✅ Backup Script Execution: Manual and automated backup creation
• ✅ Backup Content Validation: Schema inspection, data completeness
• ✅ Cron Job Integration: Automated backup scheduling and execution
• ✅ Log File Validation: Proper logging and error reporting
• ✅ Retention Policy: Old backup cleanup verification

Backup Content Verification

-- Verified backup contains complete schema and data
SHOW TABLES;        -- ✅ All tracker tables present
SELECT COUNT(*) FROM torrust_tracker_keys;  -- ✅ Data preserved
-- Full restoration capability confirmed

🏗️ Twelve-Factor Architecture Compliance

This implementation maintains strict twelve-factor app principles:

• Config: Environment variables for all settings
• Build/Release/Run: Clear separation maintained
• Backing Services: MySQL treated as attached resource
• Processes: Stateless backup script design
• Logs: Structured logging to files and stdout

🔧 Configuration

Enable Backup Automation

# In environment files (.env, local.env, production.env)
ENABLE_DB_BACKUPS=true
BACKUP_RETENTION_DAYS=7

Backup Storage

• Location: /home/torrust/backups/mysql/
• Format: tracker_backup_YYYY-MM-DD_HH-MM-SS.sql.gz
• Retention: Configurable (default: 7 days)

🚀 Deployment Impact

For Existing Deployments

• Non-Breaking: Backup automation is opt-in via environment variables
• Default Disabled: Production environments need explicit enablement
• Resource Usage: Minimal disk space and CPU impact

For New Deployments

• Enabled by Default: Local development environments
• Zero Configuration: Works out-of-the-box with sensible defaults
• Production Ready: Full error handling and logging

📋 Migration Notes

Environment Configuration

When deploying this update:

1. Review backup settings in your environment configuration
2. Enable backups if desired: ENABLE_DB_BACKUPS=true
3. Adjust retention if needed: BACKUP_RETENTION_DAYS=14
4. Deploy normally - backup setup is automatic

Storage Requirements

• Backup Size: ~10-50KB for typical tracker databases
• Daily Growth: Minimal for tracker data
• Monitoring: Check /home/torrust/backups/mysql/ periodically

🔄 What's Next (Post-Merge)

This PR completes Phase 3 of Issue #21. The next phase will implement:

• SSL Certificate Automation (Let's Encrypt integration)
• Certificate Renewal Automation (Automatic renewal scripts)
• Production SSL Configuration (Nginx HTTPS setup)

🛡️ Security Considerations

• Access Control: Backup files have restricted permissions (600)
• Data Protection: Backups contain sensitive tracker data
• Log Security: No sensitive information logged
• Process Isolation: Backup runs as torrust user

📝 Files Changed

New Files

• application/share/bin/mysql-backup.sh - Main backup script
• docs/guides/database-backup-testing-guide.md - Testing documentation

Modified Files

• infrastructure/scripts/deploy-app.sh - Backup automation integration
• infrastructure/config/environments/local.env - Local environment config
• infrastructure/config/environments/local.defaults - Local defaults
• infrastructure/config/templates/docker-compose.env.tpl - Environment template
• docs/issues/21-complete-application-installation-automation.md - Progress tracking

---

Ready for Review ✅
All tests pass, documentation is complete, and the feature is fully functional.

---

Part of Issue #21: Complete Application Installation Automation
Phase: 3 - Database Backup Automation
Next Phase: SSL Certificate Automation

[josecelano]

ACK bb0ba2e