Canonical Domain Migration

Promote a temporary site domain to the real primary domain with backups, file moves, alias cleanup, and Nginx/SSL verification.

Purpose

Canonical domain migration promotes a new hostname to the site's primary domain. It is meant for cases where a temporary domain becomes the real production domain and the active site path should move too.

This is different from an alias. An alias adds another hostname to the same site, while canonical migration updates the site domain, slug, document root path, app metadata, Nginx config, and environment values.

Command

php artisan herne:sites:canonicalize-domain {oldDomain} {newDomain} --www-alias --move-files --backup --force

Dry Run First

Always inspect a dry run before applying a live migration:

php artisan herne:sites:canonicalize-domain fklavye.webblocksui.com fklavye.net --www-alias --move-files --backup --dry-run

Apply

After the dry run is correct, use --force for the real migration:

php artisan herne:sites:canonicalize-domain fklavye.webblocksui.com fklavye.net --www-alias --move-files --backup --force

What the Command Updates

  • Finds the existing site by oldDomain and rejects a conflicting separate newDomain site.
  • Promotes newDomain from alias to primary domain when it already belongs to the old site.
  • Updates the site slug from the new domain, such as fklavye.net to fklavye-net.
  • Moves the active path to /var/www/{newDomain}/web_root when --move-files is used.
  • Keeps www.{newDomain} as an alias when --www-alias is used.
  • Removes oldDomain from site aliases and Nginx server_name.
  • Updates app installation metadata and common app environment values such as APP_URL and APP_NAME.

Backups and Retired Path

The command requires backup behavior before destructive steps. File moves retire the old active folder under a timestamped path like:

/var/www/_retired/fklavye.webblocksui.com_YYYYMMDD_HHMMSS

Migration metadata is written so the previous domain, aliases, paths, and app install state can be reviewed if rollback work is needed.

Verification

  • nginx -t must pass before reload.
  • The enabled Nginx config should contain only the new canonical domain and expected aliases.
  • The old domain must not remain as a site domain, alias, or Nginx server_name.
  • curl -I https://{newDomain} and curl -I https://www.{newDomain} should return the expected live responses.
  • http:// requests should redirect to HTTPS according to the site policy.