4.1 KiB
XC_VM Migration Guide
Safely migrate from compatible IPTV systems using the built-in XC_VM migration tools.
Critical Migration Notice
Read this before starting the migration.
XC_VM migration transfers data only. All configuration is intentionally excluded from migration.
This includes (but is not limited to):
- API keys (e.g. TMDb)
- External service credentials
- Environment-specific settings
- Panel and system configuration
- Runtime and stream state
These values must be reconfigured manually after migration.
This is a design decision, not a limitation or a bug. Skipping reconfiguration will break metadata fetching, stream title updates, and related features.
Before You Start
💡 Recommendation: Perform migration on a fresh XC_VM installation.
⚠️ Important: System and panel settings are NOT migrated. Only database data supported by the migration process is transferred.
If you choose to migrate into an existing installation, be aware:
- XC_VM will delete all tables in the main database that match data from the migration database.
- Backups are mandatory. No automatic rollback is provided.
Migration Steps
1. Upload Backup
Upload your existing database backup to the XC_VM server using SFTP.
Example location:
/tmp/backup.sql
2. Restore Backup into Migration Database
Clear the migration database and restore the backup:
sudo /home/xc_vm/console.php tools migration "/tmp/backup.sql"
Ensure the restore completes without errors before proceeding.
3. Start Migration
Once the backup is restored, start the migration using one of the following methods.
Option 1 — Command Line (Recommended)
/home/xc_vm/console.php migrate
Option 2 — Web Installer
- Return to the web installer (link shown during panel setup)
- Select Migration
- Follow the on-screen instructions
You will see real-time progress updates. Once completed, the system will be accessible.
Restoring Access After Migration
If login fails due to missing credentials or access code, use the rescue tools.
Create a Rescue Access Code
sudo /home/xc_vm/console.php tools access
Create an Administrator Account
sudo /home/xc_vm/console.php tools user
⚠️ After regaining access, immediately change the access code and administrator credentials.
Load Balancer Preparation
Load balancers are not migrated.
- Reinstall the operating system if required
- Reconfigure networking and routing
- Reconnect them to the main server
Post-Migration (Required)
After migration, the system is not production-ready until these steps are completed.
Skipping them will result in expected but broken behavior.
1. Reinitialize Runtime State
- Start all streams manually
- Verify streams are accessible and stable
Stream runtime state is never preserved during migration.
2. Reconfigure System Settings
Review and restore all environment-specific configuration:
- File paths
- Limits and quotas
- Networking and reverse proxy settings
- Performance tuning
Do not assume default values match your previous setup. Defaults are applied intentionally.
3. Restore API Keys and Providers
API Keys Are Never Migrated
The following must be reconfigured manually:
- TMDb API key
This is expected behavior.
If metadata fetching does not work after migration, verify that the API key has been re-added and the provider is enabled. This does not indicate a migration bug.
Common Post-Migration Issues
Metadata Is Not Fetching (TMDb)
Cause: TMDb API key and provider configuration were not restored.
Resolution: Re-add the TMDb API key and enable the provider in main server settings.
Summary
- Migration transfers core application data only
- Configuration is excluded by design
- API keys and environment-specific settings must be restored manually
- Missing functionality after migration is expected until reconfiguration is complete