Skip to main content

Migration

Whether you're upgrading to a more powerful PCS or moving to a different location, the migration feature lets you transfer all your apps and data to a new device.

How Migration Works​

The migration process creates a secure connection between your old PCS (source) and your new PCS (target), then transfers all app data and configurations. The pipeline has several stages:

StageWhat happens
PreparationThe source PCS packages all app data for transfer
TransferData is copied securely from source to target over the network
VerificationThe target PCS verifies all data was received correctly
ActivationThe target PCS starts all apps with the transferred data
DNS UpdateYour domain routing is updated to point to the new PCS

Before You Migrate​

Prerequisites​

  • Both PCS devices must be online and connected to the internet
  • The new PCS must have enough disk space for all your data
  • Both devices should be on the same software version (or the target should be newer)

  1. Create backups of all important apps from Admin Panel → Apps on your old PCS. Even though migration copies everything, having separate backups is good insurance.

  2. Check disk usage on your old PCS from Admin Panel → Resources → Disk tab. Make sure your new PCS has at least this much free space.

  3. Note your apps — Go to Admin Panel → Apps and note which apps are installed and their backup status.

  4. Inform users — If other people use your apps, let them know there will be a brief period of downtime during the migration.

Starting a Migration​

On the New PCS (Target)​

  1. Set up the new PCS and complete the initial configuration.
  2. Go to Admin Panel → Migration.
  3. The page will show the migration interface with a connection setup.

On the Old PCS (Source)​

  1. Go to Admin Panel → Migration.
  2. Follow the instructions to initiate the migration to the target PCS.
  3. The two devices will establish a secure connection.

During Migration​

  • The migration progress is shown in real-time on both devices.
  • Do not power off either device during the migration.
  • Do not modify apps or data on the source PCS while migration is in progress.
  • Migration time depends on the amount of data and your network speed.

After Migration​

Verify Everything Works​

  1. On the new PCS, go to Admin Panel → Apps and verify all apps are listed.
  2. Open each app in your browser and confirm data is intact.
  3. Go to Admin Panel → Health and click Run now to verify system health.
  4. Check Admin Panel → Domain to confirm routing is pointing to the new PCS.

Common Post-Migration Tasks​

  • Update bookmarks if the IP address changed
  • Reconnect mobile apps (Immich, Nextcloud, etc.) if the URL changed
  • Verify backups — Create new backups on the new PCS
  • Check certificates — Go to Admin Panel → Certificates and verify they're valid

Troubleshooting Migration​

IssueSolution
Migration stuck at transferCheck network connectivity between both devices. Ensure neither has gone to sleep.
Not enough disk spaceFree up space on the target or remove unnecessary apps from the source before migrating.
Apps not starting after migrationRun a self-check from Health → Run now. Check individual app logs from Terminal.
Domain not resolving to new PCSRun a self-check to update DNS routing. It may take up to 24 hours for DNS to propagate.
Some data missingCheck if the app stores data in a non-standard location. Restore from the backup you created before migration.

Migration from Other Platforms​

If you're migrating from a non-PCS setup (e.g., a regular server running Docker), you can:

  1. Install the same apps on your PCS from the CasaOS App Store.
  2. Copy your data to the PCS using SCP or rsync: 
    # From your old server
    rsync -avz /path/to/app-data/ admin@<pcs-ip>:/DATA/AppData/<app-name>/
  3. Restart the app on the PCS to pick up the imported data.
warning

When migrating from other platforms, ensure the directory structure matches what the PCS app expects. Check the app's documentation for the expected data layout.

tip

Always create a backup on your old PCS before starting migration. It's the safety net that lets you recover if anything goes wrong.