Skip to content

Migration settings

The content mirror copies site content from a source platform. Developer detail is in content mirror design.

migration

These settings copy the content of every site from the same site on a source platform into the local storage of this platform. Use them on a new stack. The source site must exist and use the same master token. The source URL is <routing.scheme>://<migration.source_domain>/<space>/<name>/. The mirror only reads from the source platform.

Setting Default Explanation
migration.enabled false Adds the site-mirror application to every site. The application writes to the site volume. The Hub and the Operator read this value at startup, so restart them after a change. Then upgrade the sites to add or remove the mirror.
migration.source_domain "" DNS name of the source platform, for example sites.example.org. Do not add a scheme, port or path. It must not be the same as routing.host. Required when migration.enabled is true.
migration.interval_seconds 3600 Seconds between two mirror cycles. The minimum is 1.
migration.delete true Deletes local files and empty directories that are not in the source. Set to false to keep them.
migration.delete_max_percent 99 The mirror does not delete when more than this percentage of the local files is stale. Valid values: 0 to 100.
migration.dry_run false Writes the planned downloads and deletes to the log and changes nothing locally. Use it to test a migration.
migration.verify_checksum false Compares the SHA-256 digest of local files that look up to date, and checks each download against the digest of the source. Without it, the mirror trusts the file size and the modification time.
migration.download_retries 3 Retries after the first failed download attempt. The minimum is 0. The default permits four attempts per file in each cycle.
migration.download_retry_delay_seconds 5 Fixed delay in seconds between failed download attempts. The minimum is 0. There is no delay before the first attempt or after the last failed attempt.

In each cycle, the mirror lists the source site and does these steps:

  1. It downloads each file that is not local, has a different size, or has a newer modification time in the source. It sets the local modification time to the source modification time.
  2. It creates the empty directories of the source.
  3. It deletes the local files and empty directories that are not in the source. It does not delete when the source has no files, or when the delete would remove more than migration.delete_max_percent of the local files.

The source lists a symbolic link as a regular file or directory, so the mirror copies the content of a link as regular files. It does not create symbolic links.

Each download goes to a work directory (.mirror, next to the content directory) and then moves into place. The web server does not see a partial file. If a download fails after all retries, the mirror keeps the existing local file, reports the error, continues with the other files, and tries the file again in the next cycle.

At the start of each cycle, the mirror lists the source site content. If the source site does not exist or is not reachable, or the master token is not valid, the mirror writes one error to the log and skips the cycle. It changes nothing locally, and it checks the source again in the next cycle.

While migration.enabled is true, the mirror overwrites or deletes local changes to the content. Do not let users change the content of the new stack until the migration is complete.

To migrate a platform:

  1. Create the new stack and restore the site definitions from the original stack. The restore does not copy site content.
  2. Set migration.enabled: true and migration.source_domain to the domain of the original stack. Optionally set migration.dry_run: true first.
  3. Restart the Hub and the Operator, then use Force Upgrade All Sites.
  4. Read the logs of the site-mirror container of each site. The line cycle finished: downloaded=... failed=0 shows a complete cycle.
  5. After the last complete cycle, set migration.enabled: false, restart the Hub and the Operator, and use Force Upgrade All Sites to remove the mirror.