# Copyright 2024-2025 New Vector Ltd # Copyright 2025-2026 Element Creations Ltd # # SPDX-License-Identifier: AGPL-3.0-only """ Main CLI entry point for the migration script. """ import argparse import logging import sys from dataclasses import dataclass, field from .engine import MigrationEngine from .inputs import InputProcessor, ValidationError from .models import MigrationError from .outputs import generate_helm_values, write_outputs LOADING_STEP = "Loading and validating input files" MIGRATING_STEP = "Migrating configuration to ESS values" GENERATING_VALUES_STEP = "Generating Helm values" WRITING_OUTPUTS_STEP = "Writing output files" logger = logging.getLogger("migration") @dataclass class ProgressReporter: """Handles progress reporting for the migration process.""" pretty_logger: logging.Logger verbose: bool = field(default=False) current_step: int = field(default=-1) all_steps: list[str] = field(default_factory=list) def __post_init__(self): # List of steps and the order we expect to report self.all_steps = [ LOADING_STEP, MIGRATING_STEP, GENERATING_VALUES_STEP, WRITING_OUTPUTS_STEP, ] def start_migration(self): """Report migration start.""" self.pretty_logger.info("šŸš€ Starting Matrix Stack to ESS Migration") def report_step(self, step_name: str): """Report progress on a specific step.""" if step_name != self.all_steps[self.current_step + 1]: raise MigrationError("Migration engine tried to run an unexpected step") self.current_step += 1 progress = self.current_step / len(self.all_steps) * 100 self.pretty_logger.info(f"šŸ“¦ Step {self.current_step}/{len(self.all_steps)} ({progress:.0f}%): {step_name}") def report_success(self, output_dir: str): """Report successful completion.""" self.pretty_logger.info("āœ… Migration completed successfully!") self.pretty_logger.info(f"šŸ“ Output files written to: {output_dir}") self.pretty_logger.info("šŸŽ‰ Ready to deploy with Element Server Suite!") def report_failure(self, error: str): """Report migration failure.""" self.pretty_logger.info("āŒ Migration failed!") self.pretty_logger.info(f"šŸ’„ Error: {error}") self.pretty_logger.info("šŸ“š Check logs for details and try again.") def main() -> int: """Main entry point for the migration CLI.""" # Set up argument parsing parser = argparse.ArgumentParser( description="Migrate Matrix Stack configurations to Element Server Suite Helm values", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=""" Examples: # Basic migration with Synapse only python -m migration --synapse-config synapse.yaml # Verbose output for debugging python -m migration --synapse-config synapse.yaml --verbose """, ) parser.add_argument( "--synapse-config", required=True, help=( "Path to Synapse homeserver.yaml configuration file. " "This is the main Synapse configuration that contains server_name, database, listeners, etc." ), ) parser.add_argument( "--mas-config", required=False, help=("Path to Matrix Authentication Service config.yaml configuration file. "), ) parser.add_argument( "--output-dir", default="output", help=( "Output directory for generated files (default: output). " "The migration will create Helm values.yaml and any ConfigMap files in this directory." ), ) parser.add_argument( "--verbose", action="store_true", help="Enable verbose logging. Shows detailed information about the migration process.", ) parser.add_argument( "--debug", action="store_true", help="Enable debug logging. Shows debug information about the migration process.", ) parser.add_argument( "--quiet", action="store_true", help="Disable migration summary output.", ) # Parse arguments args = parser.parse_args() # Set up logging sh = logging.StreamHandler() logger.addHandler(sh) sh.setFormatter( logging.Formatter( "%(asctime)s - %(levelname)s - %(message)s", ) ) if args.debug: logger.setLevel(logging.DEBUG) elif args.verbose: logger.setLevel(logging.INFO) else: logger.setLevel(logging.CRITICAL) pretty_logger = logging.getLogger("migration:summary") pretty_logger.propagate = False pretty_logger.setLevel(logging.CRITICAL if args.quiet else logging.INFO) pretty_sh = logging.StreamHandler() pretty_sh.setFormatter( logging.Formatter( "%(message)s", ) ) pretty_logger.addHandler(pretty_sh) # Set up progress reporter reporter = ProgressReporter(pretty_logger=pretty_logger) try: reporter.start_migration() # Load migration input reporter.report_step(LOADING_STEP) input_processor = InputProcessor() input_processor.load_migration_input( name="synapse", config_path=args.synapse_config, ) if args.mas_config: input_processor.load_migration_input( name="matrixAuthenticationService", config_path=args.mas_config, ) # Run migration reporter.report_step(MIGRATING_STEP) engine = MigrationEngine(input_processor=input_processor, pretty_logger=pretty_logger) ess_values = engine.run_migration() # Generate outputs reporter.report_step(GENERATING_VALUES_STEP) helm_values = generate_helm_values(ess_values) # Write outputs reporter.report_step(WRITING_OUTPUTS_STEP) write_outputs( helm_values=helm_values, secrets=engine.secrets, configmaps=engine.configmaps, output_dir=args.output_dir, ) # Display migration summary pretty_logger.info("\nšŸ“Š MIGRATION SUMMARY") pretty_logger.info("=" * 60) # Create a comprehensive mapping of source config paths to target ESS paths migration_mapping = {} # Process migrations for migrator in engine.migrators: migration_input = engine.input_processor.input_for_component(migrator.component_root_key) # Migrators are created according to discovered input for components, we do not expect NoneTypes here assert migration_input source_file = migration_input.config_path for transformation_result in migrator.results: source_path = transformation_result.spec.src_key target_path = transformation_result.spec.target_key migration_mapping[source_path] = (source_file, target_path) # Show successfully migrated values with source and target mapping if migration_mapping: pretty_logger.info("āœ… SUCCESSFULLY MIGRATED TO ESS:") for source_path, (source_file, target_path) in sorted(migration_mapping.items()): pretty_logger.info(f" • {source_file}: {source_path} → {target_path}") pretty_logger.info("") if engine.ess_config["synapse"].get("workers"): pretty_logger.info("šŸ“ Discovered and enabled the following Synapse workers") for worker_type, worker_props in engine.ess_config["synapse"]["workers"].items(): pretty_logger.info(f" - {worker_type} (replicas: {worker_props['replicas']})") # ask user to take a second look pretty_logger.info(" āš ļø Please review the workers in your values files before proceeding.\n") else: pretty_logger.info(" āœ… No workers found, using a single main Synapse process") if engine.discovered_secrets: pretty_logger.info("šŸ” MIGRATED SECRETS:") for discovered_secret in engine.discovered_secrets: pretty_logger.info( f" • {discovered_secret.source_file}: {discovered_secret.config_key} → " f"{discovered_secret.secret_key}" ) if engine.init_by_ess_secrets: pretty_logger.info("\nāš ļø ESS-INITIALIZED SECRETS:") pretty_logger.info("The following Synapse secrets will be auto-generated by ESS:") for secret in engine.init_by_ess_secrets: pretty_logger.info(f" • {secret}") pretty_logger.info( "These secrets are not required for migration but will be created automatically during deployment." ) # Show override warnings within the migration summary if engine.override_warnings: pretty_logger.info("\nāš ļø ESS-MANAGED CONFIGURATIONS FOUND:") pretty_logger.info(" These settings are managed by ESS and will be overridden:") pretty_logger.info("") for warning in engine.override_warnings: pretty_logger.info(f" • {warning}") pretty_logger.info("") pretty_logger.info("ā— ACTION REQUIRED:") pretty_logger.info(" Remove these settings from your additional configuration to avoid conflicts.") pretty_logger.info(" They are now automatically managed by the ESS Helm chart.") pretty_logger.info("") # Show clean migration message if not engine.override_warnings: pretty_logger.info("šŸŽ‰ CLEAN MIGRATION: No unexpected overrides detected!") pretty_logger.info(" All configurations have been properly migrated to ESS.") pretty_logger.info("") pretty_logger.info("=" * 60) reporter.report_success(args.output_dir) logging.info("Migration completed successfully!") logging.info(f"Output files written to: {args.output_dir}") return 0 except ValidationError as e: reporter.report_failure(str(e)) logging.error(f"Input validation failed: {e}") return 1 except Exception as e: reporter.report_failure(str(e)) logging.error(f"Migration failed: {e}") return 1 if __name__ == "__main__": # Run the main function exit_code = main() sys.exit(exit_code)