---
title: "Cut over to the new site, or roll back"
url: https://docs.corefinity.com/mcp/playbooks/cutover-and-rollback
type: playbook
last_updated: 2026-11-13
---
# Cut over to the new site, or roll back

Move a migrated site's live domain from the old host, keeping the switch-over short: freeze the old host, take the final copy, switch DNS and release the holds in order; or roll back, before or after DNS moved.

Prompt name: `cutover-and-rollback`

## Arguments

- `site` (required): The migrated site: its domain, or the id of any of its environments.
- `domain` (required): The live domain being moved, for example shop.example.com.
- `environment`: The target environment's name, for example Production. Without it the playbook works on production when this token may, otherwise on the first environment it may.
- `strategy`: How the copy was tested before DNS: rewrite-urls (its URLs pointed at the platform hostname) or pending-dns (the domain attached as pending DNS).

## Starting prompt

```text
Use the Corefinity MCP prompt "cutover-and-rollback" with site: <the migrated site: its domain, or the id of any of its environments>, domain: <the live domain being moved, for example shop.example.com>, environment: <the target environment's name, for example production. without it the playbook works on production when this token may, otherwise on the first environment it may>, strategy: <how the copy was tested before dns: rewrite-urls (its urls pointed at the platform hostname) or pending-dns (the domain attached as pending dns)>. Follow it step by step and tell me before anything that changes my account.
```

## What the assistant is told

Purpose: move <domain> from its old host to the migrated site keeping the switch-over short, then keep a way back. Run
it after the stack's playbook (`migrate-wordpress`, `migrate-magento`, `migrate-laravel`, `migrate-shopware` or `migrate-php`) has made a trial copy that passed its tests. The Control
Panel never connects to the old host: you work on it with your own access, and the person decides every step that
changes something.

## What you were given

- The live domain being moved: <domain>.
- The target row: <the id of the site row you work on> (<the environment's name>).
- The strategy chosen before DNS: <strategy>. `rewrite-urls` is strategy 1 and `pending-dns` strategy 2 (below).
  When not given, read the row's `hosts` in the target facts: a domain attached as pending DNS means strategy 2.

## Before you start

- This token must stay valid until the move ends: revoking it, or its expiry, stops its running commands and
  transfers (rule 11). If it would expire before the cutover, ask the person for a token that lasts.
- Ask the person before every write to the production row (rule 14). If a call is refused because this token lacks a
  scope or the site is outside its limits, the person is asked to allow it in the Control Panel; carry on once they
  have.
- Two ways to test the copy before DNS moves; the cutover uses one of them:
  - **Strategy 1, rewrite the URLs:** `corestack_site_rewrite_urls` points the copied application at the row's
    platform hostname, so it can be tested before DNS moves; `corestack_site_rewrite_urls_restore` puts the saved
    originals back.
  - **Strategy 2, attach as pending DNS:** `corestack_site_attach_domain` with `pending_dns` true: the row answers for
    the real domain at its ingress address before DNS points there, and you test it with `corestack_site_smoke_test`
    and `host` set to the domain. The attach keeps the copy inert; the cutover completes it. Each host that does not
    point there yet needs its proof of control: a refusal on `hosts` names a TXT record and its value, which the person
    adds at their DNS provider; then attach again.
- Values in angle brackets are yours to fill: `<site-root>` (the target row's directory, `/var/www/` and the row's own
  domain, as the target facts' `paths` give it), `<host>` and `<port>` (the row's SSH host and port, from the target
  facts), `<platform-host>` (the row's platform hostname), `<old>` (the old host as you reach it), `<old-root>` (the
  application's directory there), and the like.
- The target row's own domain can differ from the live domain being moved (a `www.` form, a staging row): `<site-root>`
  and `confirm_domain` always take the row's own domain, read from the target facts, never the live domain.

## Rules for every migration

1. **Facts first.** Call `corestack_site_target_facts_get` with the application and version you found on the old host (the stack's step 1):
   with `site_id` when the target exists; with no target yet, with `placement` — `{kind: "cluster", cluster_id}` or
   `{kind: "platform", region}`, whichever rule 13 picks — for the verdict and the create lists, then again with
   `site_id` once the create has finished, for the row's paths, database, environment names, SSH, hosts and outbound
   addresses. A verdict other than `supported` stops the move: tell the person what to upgrade. **An existing
   target's versions come first** (the facts' `current`): carry out `current.actions` before anything is copied or built —
   `corestack_php_version_change {to}` (wait for its task; acknowledge only what it asks and the person has accepted),
   `corestack_mariadb_version_change` once per forward step, each awaited, until the facts read again report
   `php_in_range` and `mariadb_in_range` and the target's versions; `new_target` means this row cannot take the
   application (its MariaDB is newer than the application supports, and no step back exists) — stop and offer the
   person a new target (rule 13). The target ends on exactly `target`'s PHP and MariaDB — a PHP inside the range
   but below `target` is changed too, saying so; a version change that is refused or fails stops the move until it
   succeeds. On the production row ask first (rule 14).
2. **The old host is yours, never the Control Panel's.** You put it into maintenance and comment out its crontab, and you
   keep a copy of what you changed so you can undo it. **Never kill, stop or interfere with a process on the old host** — no
   `kill`, `pkill`, `systemctl stop`, `supervisorctl stop`; wait for running jobs to finish on their own.
3. **Credentials are yours.** Corefinity stores none. Prefer a key generated for the move and removed after it;
   keep passwords out of argv where you can (`--defaults-extra-file`, `MYSQL_PWD`), because commands are logged in
   redacted form only on a best-effort basis.
4. **Three ways to move files** — pick by what the old host allows; **A is the default**:
   - **A. Pull inside the pod** — the target fetches from the old host over SSH, so nothing on the old host needs to
     reach Corefinity. If the old host filters inbound SSH, ask the person to allow the target's outbound addresses
     (`outbound_ips.addresses` from the facts — the region's Cloud NAT addresses) on it, and remove them after the
     move. Only when the facts say `outbound_ips.fixed: false` (this site's servers do not use fixed outbound
     addresses) is there nothing stable to allow: then use B or C, unless the old host does not filter.
     ```sh
     # in the target, with corestack_exec_command (cwd: the site root)
     install -d -m 700 <site-root>/.move
     ssh-keygen -q -t ed25519 -N '' -C corestack-move -f <site-root>/.move/id_ed25519
     chmod 600 <site-root>/.move/id_ed25519       # the site's files default to readable by others; ssh refuses such a key
     cat <site-root>/.move/id_ed25519.pub        # add this line to <old>'s ~/.ssh/authorized_keys yourself
     ssh-keyscan -t ed25519 <old-hostname> > <site-root>/.move/known_hosts
     ssh-keygen -lf <site-root>/.move/known_hosts # compare with `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` run ON <old>
     rsync -rlptDz --partial --stats --keep-dirlinks --chmod=Du=rwx,Dgo=rx,Fu+rw,Fgo-w,Fgo+r \
       -e 'ssh -i <site-root>/.move/id_ed25519 -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=<site-root>/.move/known_hosts' \
       --exclude-from=<site-root>/.move/excludes <user>@<old-hostname>:<old-root>/ <site-root>/htdocs/
     ```
     Run it with `corestack_exec_command`, `timeout_seconds` sized to the data and `wait_seconds: 0`; follow the task.
   - **B. Push from the old host to the target's SSH host** (the old host can reach `<host>:<port>`):
     ```sh
     # on <old>
     ssh-keygen -q -t ed25519 -N '' -C corestack-move -f ~/.ssh/move_to_corestack
     # corestack_ssh_quick_setup {site_id: <the id of the site row you work on>, public_key: <~/.ssh/move_to_corestack.pub>} → wait for its task;
     # write its known_hosts lines to ~/.ssh/move_to_corestack_known_hosts
     rsync -rlptDz --partial --stats --keep-dirlinks --chmod=Du=rwx,Dgo=rx,Fu+rw,Fgo-w,Fgo+r \
       -e 'ssh -p <port> -i ~/.ssh/move_to_corestack -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=~/.ssh/move_to_corestack_known_hosts' \
       --exclude-from=excludes <old-root>/ web@<host>:<site-root>/htdocs/
     ```
   - **C. Signed URL** (the old host has only outbound HTTPS):
     ```sh
     # on <old>; GNU tar; `tar -czf …tar.gz` where zstd is missing
     tar --zstd -cf /tmp/site.tar.zst --anchored --exclude-from=excludes.tar -C <old-root> .
     stat -c %s /tmp/site.tar.zst; sha256sum /tmp/site.tar.zst
     # corestack_transfer_upload_create {site_id, filename: "site.tar.zst", size_bytes, sha256}
     # → run the curl line it returns: one PUT of the whole file to the upload session, or its chunked lines for a
     #   large file over a flaky link (the session is the Control Panel's; it ends with the transfer)
     # → corestack_files_sync {site_id, transfer_id, target_path: "htdocs", delete_extraneous: false,
     #                         excludes: [the stack's list, rsync form — its step 4]}
     ```
   - **Flags, always:** `-rlptD` (never `-o` / `-g`: files must belong to `web`); `--keep-dirlinks` so a shared-path
     link on the target stays a link; `--chmod` as above (directories 755, files keep their execute bits, never group-
     or world-writable); `--partial` so a broken pass resumes; **no `--delete` in the first pass**; the cutover's last
     pass adds `--delete-after`. The excludes of each stack always include the target's own platform files (each stack's step 4), so neither a copy nor a deletion touches them. For `tar`, the same list with each leading `/` written
     `./`. **On path C pass the stack's list as `excludes[]` to every `corestack_files_sync` call** — the first and the
     cutover's deleting one alike: leaving a path out of the archive does not protect the target's copy of it from a
     sync with `delete_extraneous`, only `excludes[]` do (an excluded destination path is never overwritten
     or deleted), so without them a deleting sync would remove Laravel's `vendor/`, Shopware's `public/theme/` or the
     WooCommerce target hold.
5. **Three ways to move the database** — all end in `corestack_db_import`, which takes a safety snapshot, sanitises
   definers and GTID lines, and on the production row asks for `confirm_domain` and, the first time, a step-up:
   - dump on the old host → `corestack_transfer_upload_create` → `corestack_db_import {transfer_id}` (path C);
   - dump on the old host → `rsync` / `scp` to `web@<host>:<site-root>/.move/db.sql.zst` (path B) →
     `corestack_db_import {path: ".move/db.sql.zst"}`;
   - from the pod (path A): the same two passes run on `<old>` over `ssh`, compressed in the pod into
     `<site-root>/.move/db.sql.zst.part`, checked and renamed as below, then the same `{path}` import.
   **A dump is used only when it is complete.** Both passes — the data, and the structure of the tables whose rows
   are left out — feed **one** compressor (never a plain-SQL pass appended to a compressed file); the pipeline runs
   with `pipefail`, so a failed `ssh` or dump fails it even though the compressor ended cleanly; the output goes to
   `.part` and is renamed only after the archive tests whole and every pass's own trailer line is in it — a partial
   dump is never uploaded or imported (an import with `drop_existing_tables` would replace the target with it). Any
   earlier `db.sql.zst` is removed **before** the dump starts, and a failed or incomplete dump ends the command with a
   non-zero exit — so a failure never leaves an older dump in place for the next step to upload or import:
   ```sh
   # on the old host (bash) — or the same lines inside `ssh … <old> '…'`, with the compressor in the pod
   set -o pipefail
   rm -f db.sql.zst db.sql.zst.part   # never an older dump beside a failed one
   dump() {   # MySQL's mysqldump (5.7 / 8.x); MariaDB's mariadb-dump: drop the last two flags
     mysqldump --defaults-extra-file=<0600 file> --single-transaction --quick --routines --triggers --events \
       --hex-blob --no-tablespaces --default-character-set=utf8mb4 --max-allowed-packet=1G \
       --set-gtid-purged=OFF --column-statistics=0 "$@"
   }
   { dump <db> --ignore-table=<db>.<table> …  &&  dump --no-data <db> <table> … ; } | zstd -T0 -3 > db.sql.zst.part \
     && zstd -t db.sql.zst.part \
     && [ "$(zstd -dc db.sql.zst.part | grep -c '^-- Dump completed')" -eq 2 ] \
     && mv db.sql.zst.part db.sql.zst \
     || { echo 'STOP: the dump failed or is incomplete' >&2; rm -f db.sql.zst.part; false; }   # exits non-zero
   ```
   (`--column-statistics=0` only on a MySQL 8 client; with no table left out, run the first pass alone and expect one
   trailer; where `zstd` is missing, `gzip -c` / `gzip -t` / `gzip -dc` the same way.) Which tables' rows a dump leaves
   out depends on **which copy it is**: a trial copy leaves out the queue tables' rows as each stack's step 6 lists, the cutover's final dump keeps them (step 7 of `cutover-and-rollback`).
6. **Config points at the platform**, never at literal credentials: the target's database, cache and search
   settings come from the pod's environment (the stack's steps give the exact keys). Keep the application's own secrets — salts,
   `crypt/key`, `APP_KEY` — from the source.
7. **Git-mode target:** if the facts' `deploy_mode` is `git`, call `corestack_deployments_mode_set {mode: "manual"}`
   first and wait for its task. Leave it manual; at the end tell the person to switch back to Git with the same tool or
   the Control Panel when they are ready. This holds for Laravel too. A WordPress target built with Bedrock refuses the switch
   (`bedrock_layout`): stop the move there and copy nothing. This playbook's holds, loader and file paths are those of a
   classic WordPress site, and a Bedrock site loads its must-use plugins from `app/mu-plugins`, so the copy's hold would
   not load. Tell the person the site stays on Git deployments and offer to move into a site that is not built with
   Bedrock. `layout_unknown` means its layout could not be confirmed: call the tool again in a minute, and stop the same
   way if it still cannot be confirmed.
8. **Before long work** check `corestack_pending_changes_list`: maintenance queued for tonight replaces the pod and ends a running
   command (`container_replaced`); do not start a long copy that would still be running when it applies.
9. **Hold the copy before its first import, release it only at cutover.** The target must not act as the live site
   while the original serves: no scheduled job, queue, renewal or real mail may start on it — whether it is a new
   target, an existing row, a strategy-1 rewrite or a pending-DNS attach. Before the first database import, on every
   platform (WordPress included — a new production row is born production-ready, so its only cron gate is Scheduled tasks):
   - **Scheduled tasks off:** `corestack_crons_get`, then `corestack_crons_update` with the same entries, its `version`,
     `enabled: false` and `builtin_enabled: false` (the update replaces the whole set). This stops WordPress's
     `wp cron` (WooCommerce's Action Scheduler: renewals, scheduled sales), the Laravel scheduler, Magento's `cron:run`
     and the queue consumers it starts, and Shopware's scheduled tasks. A pending-DNS attach keeps them off;
     an ordinary attach at cutover switches only the site switch on.
   - **Queue consumers held — Magento 2, Laravel, Shopware** (the facts' `hold.queue`): Scheduled tasks do not reach
     the queue container, so call `corestack_site_copy_hold_set {site_id, consumers: true}` and wait for its task —
     it completes only once the consumers have drained and none runs. The hold needs an adopted row: a new
     target is born adopted; an existing one that answers `runtime_not_adopted` is adopted first with
     `corestack_runtime_adopt` (before the first import), after telling the person. It stays on through every import, test
     and attach until step 10 of `cutover-and-rollback`, so work the copy itself enqueues (a smoke test, an admin click, a build command)
     waits and never runs on the copy. WordPress has no queue container: Scheduled tasks and the hold file below are
     its holds.
   - **Every import behind a web hold:** before each `corestack_db_import` (the first and every later one, the
     cutover's included), `corestack_site_copy_hold_set {web: true}` — 503 to every client, the office address
     included — so nothing reaches the copy while its tables are dropped and refilled (a WordPress installer, a
     Shopware storefront on half a database) or before the holds the import overwrote are back. After the import, put
     back what this rule and the stack's settings step set (WordPress: the table prefix first, then the SMTP plugins;
     Magento: step 8 of `migrate-magento`; Shopware: step 8 of `migrate-shopware`, and staging mode on a non-production row, its step 8a), check them,
     and only then `{web: false}` to test.
   - **Queues start empty in a trial copy:** the stack's trial dump leaves the queue tables' rows out (the stack's step 6), so nothing queued on the source runs on the copy (Shopware also resets the scheduled tasks those messages
     belonged to, in its step 6). The cutover's final dump keeps them, and they run once, on the target, when the
     consumers are released (steps 7 and 10 of `cutover-and-rollback`).
   - **Mail:** no sending domain on the target until cutover — `corestack_email_get` shows it not set up (a v3
     production row drops every send until one exists); if an existing target already sends, ask the person before
     the first import whether to pause it (`corestack_email_disable`) or accept that the copy's mail is real. Magento:
     `system/smtp/disable 1` at every scope, `env.php`'s locks included (steps 7–8 of `migrate-magento`; a pending-DNS attach keeps it). WordPress: deactivate third-party SMTP plugins after each import, once the table prefix is set (step 6 of `migrate-wordpress`; `wp plugin deactivate <smtp plugin>`). Shopware: the email agent of step 8 of `migrate-shopware` and
     `core.mailerSettings.disableDelivery` `true --json` after each import, from the first — before any attach, as
     Magento's `system/smtp/disable 1` (a pending-DNS attach keeps it).
   - **WooCommerce:** Action Scheduler also runs due actions from admin page loads (its async queue runner); write the
     target's hold file `wp-content/mu-plugins/000-corestack-target-hold.php` with
     `<?php add_filter('action_scheduler_allow_async_request_runner', '__return_false');` (with `corestack_file_write`),
     so no renewal is processed on the copy.
   - **Payments:** never complete a live-mode payment while testing.

   Re-check the holds after each import (an import overwrites the database, not the Control Panel's switches, the copy hold or
   the hold file). Step 10 of `cutover-and-rollback` releases them in order.
10. **Verify** with `corestack_site_smoke_test` (or `corestack_site_http_check` on a read token) and read the errors it
    lists; fix, then test again.
11. **Keep the token alive:** a revoked or expired token cancels its running commands; if a long copy is cut off
    with `grant_revoked` / `grant_expired`, ask the person for a token that lasts, then run the step again (every step
    is re-runnable).
12. **Clean up** at the end: `rm -rf <site-root>/.move` and the target's hold file (rule 9) if the cutover has not already; a move given up before its cutover releases the copy hold too (`corestack_site_copy_hold_set
    {consumers: false, web: false}`) once the person agrees — it never lapses by itself; remove the move key from the old host's
    `authorized_keys` and from the target (`corestack_ssh_user_key_delete`), and the target's addresses from the old
    host's firewall if you added them (rule 4); transfers expire by themselves after 24 h.
13. **Make the target the platform's way** (when no `site` is given): `corestack_in_corecluster_site_create` when the
    company has a CoreCluster with space (check `corecluster_capacity_check` first, on `cluster` when it is given),
    otherwise `corestack_site_create`. A pinned token may create a site only inside a CoreCluster that one of its
    `cluster` pins covers (a token pinned only to sites or environments there steps up to add the cluster
    pin); `corestack_site_create` is refused to every pinned token. Either refusal carries a
    link — ask the person to open it and widen the token (it pre-adds that cluster, or "Everything in {Company}" for
    the standalone create), then call again.
14. **Ask the person before every write to the production row**, and type a `confirm_*` value only after they have
    said yes to that action.
15. **Bound every retry:** a failed call or check is retried at most twice; then stop and report what failed and what
    you saw.
16. **Never ask for a third-party password in a tool argument** other than your own commands; `old_host` is how
    you reach the old server ("ssh deploy@old.example.com"), never a password.
17. **PHP extensions and settings**, after the files and before the build: on the old host run `php -m` and
    `php --ini` and read the custom ini files it lists. **Read the target with `corestack_php_runtime_get {site_id}`**
    — its current optional set, locks and `version` token; use `corestack_php_catalogue_get {version: <the target's
    PHP minor>, platform}` only for what that minor offers and why (it is about a PHP minor, not the row, and carries
    no token). Turn on what the application needs with `corestack_php_extensions_update` (the **full** optional set:
    the runtime read's set plus what is missing, with the runtime read's `version` — the platform's locked extensions
    are already on), and **read the runtime again after every successful change** for the next token (a stale one is
    409 `stale`); port custom directives with `corestack_php_ini_validate` first, then `corestack_php_ini_update` (or
    `corestack_php_directives_update` for the form's directives), each with the current token. They apply straight away on an adopted row (a new target is born adopted); on a row not yet adopted the change adopts it where the platform offers that, or answers `runtime_not_adopted` with
    the row's state — adopt it with `corestack_runtime_adopt` or carry on without, and tell the person. An
    extension the catalogue does not offer cannot be uploaded: tell the person, who can request it.
18. **Node.js and builds:** set the target's Node.js version first — match the old host's `.nvmrc`,
    `.node-version` or `package.json` `engines` with `corestack_node_version_change` (the majors `node.offered` lists;
    Node 16 is never a new choice). Nothing is built on the agent's machine. **Carry the old host's build,
    database and post-deploy commands into the target's deployment pipeline:** `corestack_deployments_pipeline_check`
    with the lines (it answers each line's verdict — replaced by a platform step, path changed, needs the site's
    services, a credential to move), then `corestack_deployments_pipeline_stage_update` per stage; a credential an old command carried goes into `corestack_deployments_variable_set` or, for a package
    registry, `corestack_deployments_secret_set` — never into a line. **Check the shared files before each start** (it
    advises, never gates): `corestack_deployments_shared_files_check` with `for: "rehearsal"` on the staging environment
    before the rehearsal, and with `for: "deployment"` on the target before its deployment. Tell the person what it found
    — each missing or unreadable file's `message` names it and where to create it over SFTP or SSH — and that a copy
    their repository includes is used instead, which no check can see before the build; then start when they say so,
    whether or not they create the file. A refused check holds nothing back. **Rehearse on the staging environment**
    (`corestack_deployments_rehearse` — exec, never production — then `corestack_deployments_rehearsal_get`), then deploy
    (`corestack_deployment_trigger`) once the person has switched the site back to Git (rule 7). While the target is
    manual for the copy, the assets the copy needs come with the files from the old host (its built output) or from the
    pipeline's build lines run once in the pod with `corestack_exec_command` on the row's Node.
19. **Carry the old host's own scheduled jobs** — the target keeps only its own entries, so anything the source's
    crontab ran for the application is lost unless you move it. Carry it by the rules a Corefinity move onto CoreStack
    uses, so the set is the same whoever moves the site. From step 1's `crontab -l`:
    - **The platform's own job** — WordPress `wp cron event run --due-now` (or `wp-cron.php`), Magento `bin/magento
      cron:run` without `--group`, Laravel `artisan schedule:run`, Shopware `scheduled-task:run` — on the built-in task's
      schedule (every 5 minutes on WordPress, every minute otherwise) IS the built-in task: leave it out (step 10
      switches the built-in task on). On any other schedule carry it as an entry with that schedule and keep the
      built-in task off at step 10, so it never runs twice. Magento's legacy `update/cron.php` and `setup:cron:run` and Shopware's
      `messenger:consume` are the platform's too (the built-in line and the queue container): leave them out.
    - **Every other line** becomes one `corestack_crons_update` entry: `schedule` exactly as it ran (an `@hourly`,
      `@daily`, `@weekly`, `@monthly` or `@yearly` written as its five fields, in the form `corestack_crons_get` shows),
      `command` with the old site root replaced by `<site-root>/htdocs` (its shared folder by `<site-root>/shared`), any
      absolute or versioned PHP binary (`/usr/bin/php`, `/opt/…/bin/php`, `php7.4`) by `php`, cron's `\%` by `%`, and the
      crontab's own variable lines in force (not `MAILTO` or `SHELL`, nor a `PATH` of the standard folders) as
      `export NAME='value';` in front; `label` (what it does, ≤ 60), `no_overlap` true, `timeout` 21600 (a cron on the old
      host had no limit) unless the person wants less, and **`enabled` false**.
    - **Tell the person, never carry:** an `@reboot` line; a command with an unescaped `%` (cron feeds the rest to it as
      input); a schedule tied to a time of day or a date that the old host ran in another time zone (a `CRON_TZ`, or the
      server's own) — CoreStack runs schedules in London time; a line naming a path outside the copied site (the old
      home folder, `/etc`, another site), a service of the old host by name, or `n98-magerun` from the PATH; anything
      `corestack_crons_validate` refuses; and the application's lines in `/etc/cron.d` (the host owner's: they keep
      running on the old host until it is retired).
    Save them with the whole set, in the same update that switches Scheduled tasks off (rule 9) — at most 49 entries.
    Show the person the list and ask which to run; step 10 of `cutover-and-rollback` switches the approved ones on, with
    the site switch, at cutover.

## Steps

### Before the day

1. A full trial: do the stack's playbook (`migrate-wordpress`, `migrate-magento`, `migrate-laravel`, `migrate-shopware` or `migrate-php`) end to end, smoke-test, and **time** the database dump, transfer and import and
   the final file pass — that is how long the switch-over takes; tell the person.
2. Lower the domain's DNS TTL to 300 s at least one old TTL ahead (`corestack_domains_check_dns` shows what resolves).
3. Prefer strategy 2 for the final check: `corestack_site_attach_domain {…, pending_dns: true}` so the target answers
   for the real domain at its ingress address, then `corestack_site_smoke_test {host: <domain>, …}`. With Cloudflare
   connected, the certificate can be ready before DNS moves. The attach keeps the copy inert; it is completed
   by step 9a, never by a second attach.
4. The holds of rule 9 are in place: `corestack_crons_get` shows `enabled` and `builtin_enabled` false; the target facts' `hold.consumers` is `held` on a row with a queue (Magento 2, Laravel, Shopware);
   `corestack_email_get` shows no sending domain (or the person agreed otherwise); Magento's `system/smtp/disable` is 1
   at every scope (the check of step 7 of `migrate-magento`);
   on a Shopware target, `bin/console system:config:get core.mailerSettings.disableDelivery --format=json` answers
   `true` (step 8 of `migrate-shopware`; on a row attached as pending DNS, the attach's `mail_hold` holds it too); and
   `corestack_deployments_get` answers the mode `manual` (rule 7 — a target in Git mode is switched to manual and the
   cutover waits for that task).

### Cutover
5. **Old host into maintenance** — with a mechanism that lasts as long as the cutover and the rollback window,
   and that you can undo:
   - **WordPress:** not `wp maintenance-mode` — WordPress treats its `.maintenance` marker as stale after ten minutes
     (`wp_is_maintenance_mode()`) and starts serving again in the middle of the final copy. Write a must-use hold file
     instead, which loads on every web request (pages, `wp-cron.php`, `xmlrpc.php`, the REST API, `admin-ajax.php`)
     and leaves WP-CLI and the dump untouched:
     ```php
     <?php // <old-root>/wp-content/mu-plugins/000-corestack-move-hold.php — delete it to reopen the site
     if (PHP_SAPI !== 'cli' && ! (defined('WP_CLI') && WP_CLI)) {
         http_response_code(503);
         header('Retry-After: 3600');
         header('Cache-Control: no-store');
         exit('This site is moving and will be back shortly.');
     }
     ```
     (`mkdir -p wp-content/mu-plugins` first; a page cache that the web server serves without PHP may still show
     pages, but nothing behind it — checkout, accounts, webhooks — answers.)
   - **Magento 2:** `bin/magento maintenance:enable --ip=<your address>` (the flag file `var/.maintenance.flag` has no
     expiry).
   - **Laravel:** `php artisan down --secret=<random>` (`storage/framework/down`, no expiry).
   - **Shopware:** `bin/console sales-channel:maintenance:enable --all` (a flag on every sales channel in the
     database, no expiry).
   - **A custom PHP application** (`migrate-php`): it has no switch of its own that every script obeys, so hold it in
     the old web server's own configuration, outside the files that are copied: nginx, `return 503;` as the first
     line of the site's `server` block, then `nginx -t && nginx -s reload`; Apache, `RewriteEngine On` and
     `RewriteRule ^ - [R=503,L]` in the site's virtual host, then a graceful reload. Write down the lines you added, to
     take them out on a rollback. Where you can only reach `.htaccess`, put the same two lines at its top and keep
     that file out of the final copy (step 7). The application's own maintenance mode is fine instead when it has
     one, it does not expire and the person agrees.
   **Verify it from outside** while DNS still points at the old host: `curl -s -o /dev/null -w '%{http_code}\n'
   https://<domain>/` answers 503 (Shopware: its maintenance page), and again right before the final dump (step 7).
6. **Old crontab commented out, never deleted, nothing killed** — every active line, indented ones and `@reboot` lines
   included, with the result checked before it is installed:
   ```sh
   stamp=$(date -u +%Y%m%dT%H%M%SZ)
   crontab -l > ~/crontab.before-corestack.$stamp          # the copy you restore from ("no crontab" = nothing to do)
   sed -E 's/^([[:space:]]*)([^#[:space:]])/\1# corestack-move: \2/' ~/crontab.before-corestack.$stamp \
     > ~/crontab.during-corestack.$stamp
   if grep -Eqv '^[[:space:]]*(#|$)' ~/crontab.during-corestack.$stamp; then
     echo 'STOP: a line is still active'                    # never install a file that still runs something
   else
     crontab ~/crontab.during-corestack.$stamp
   fi
   crontab -l | grep -Ev '^[[:space:]]*(#|$)' || echo 'no active entries'   # must print only "no active entries"
   ```
   Comments and blank lines stay as they were; variable lines (`MAILTO=…`) are commented too and come back with the
   restore. Then wait until no cron job or queue worker of the application is mid-run (`pgrep -fa 'cron:run|schedule:run|queue:work|wp cron'`
   only to look; never to kill). System crontabs (`/etc/cron.d`) are the host owner's: ask the person.
   **Then the old host's queue consumers must stop before the final dump**, so that every pending and delayed job runs
   exactly once — on the target, after the cutover (step 10), never on both. Producers are already frozen (step 5)
   and the scheduler is commented out; what is left is the consumers. Laravel's `queue:work` pauses by itself while the
   application is down unless it was started with `--force` (read the worker's command line). On Magento and Shopware
   — and for a Laravel worker with `--force` — ask the person to stop the old host's worker services (supervisor,
   systemd, a Shopware admin worker in an open admin tab) once nothing is mid-job, and confirm that none remains
   (`pgrep -fa 'queue:consumers:start|messenger:consume|queue:work'` prints nothing). You never stop them yourself
   (rule 2). **If the person cannot stop them, the cutover stops here** — never a final dump with work left on
   the source: tell the person which pending and delayed jobs are queued (count, name, when due: `SELECT … FROM jobs`
   on Laravel, `queue_message_status` on Magento, `messenger_messages` on Shopware), take the old host out of
   maintenance and restore its crontab as **Rollback, before DNS moved** says (the target keeps its holds), and try
   again once the workers can be stopped. A queued job therefore runs exactly once: on the old host before the
   cutover, or on the target after it (step 10).
7. **Final copy:** the stack's file pass again with `--delete-after` (or a new archive with `corestack_files_sync`
   `delete_extraneous: true`, `confirm_domain` and **the stack's `excludes[]`** — rule 4) — the stack's excludes keep
   every maintenance marker of the old host and the target's own files out of the copy and out of the deletion
   (`/.maintenance` and the hold files on WordPress, `var/.maintenance.flag` / `.maintenance.ip` on Magento,
   `storage/framework/down` / `maintenance.php` and `vendor/` on Laravel, `public/theme/` on Shopware, an `.htaccess`
   that holds a custom PHP application) — then, under
   the web hold (rule 9), a **final dump that keeps the queue tables' rows** (step 6 of the stack's playbook names them —
   with the old host's consumers stopped in step 6 they are exactly the work still to do; caches and sessions stay
   out) and `corestack_db_import`. The database's URLs are now the originals; `env.php`'s on Magento are not (step 8).
8. **Re-apply** what the import overwrote: Magento's step 8 settings (`migrate-magento`; `system/smtp/disable 1` stays until step 9; the `env.php` locks of its step 7 were never overwritten), and **after strategy 1 on Magento, the `env.php` base-URL
   locks**: `corestack_site_rewrite_urls_restore {site_id, confirm_domain}` puts back the locked values the rewrite
   saved exactly (no import can — `env.php` is excluded from every copy) and writes back the saved database rows,
   which the final import has already made the originals; then compare every scope's `bin/magento config:show
   web/secure/base_url` and `web/unsecure/base_url` (`--scope=websites|stores --scope-code=<code>`) and the `env.php`
   `system/…/web/…/base_*url` locks with the old host's — they must match;
   Shopware's (step 8 of `migrate-shopware`, its delivery hold included — the final dump carried the old shop's `disableDelivery`, so
   without it the copy could send before step 9) **and** `bin/console
   sales-channel:maintenance:disable --all` — the final dump carries the source's maintenance flag on every sales
   channel; WordPress: the SMTP plugins off again; `wp cache flush` /
   `bin/magento cache:flush` / `php artisan optimize` / `bin/console cache:clear:all`. Then **prove the target is not
   in maintenance** before any DNS change: no `storage/framework/down` (Laravel), no `.maintenance` or move-hold file
   (WordPress), no `var/.maintenance.flag` (Magento), no sales channel with `maintenance = 1` (Shopware:
   `SELECT COUNT(*) FROM sales_channel WHERE maintenance = 1` is 0), no hold lines in a copied `.htaccess` and the
   application's own maintenance mode off (a custom PHP application); then release the web hold
   (`corestack_site_copy_hold_set {web: false}`) and `corestack_site_smoke_test` on `/` answers no 503 (on the
   pending-DNS domain, or the platform hostname). The consumers stay held until step 10.
9. **Switch** — by what the row already is (the target facts' `hosts`):
   - **a. attached as pending DNS (strategy 2):** do **not** call `corestack_site_attach_domain` again — the row is
     attached and the call is refused `already_attached`. Release what the attach held: Magento 2 — first put back
     `env.php`'s own `smtp/disable` locks at every scope (the source's values written down at step 7 of `migrate-magento`;
     `corestack_file_write` with `expected_sha256`), then put back the database's own values at every scope from
     `.move/smtp-disable.saved` (step 8 of `migrate-magento`): each saved `(scope, scope_id)` row set to its saved value, and the
     default row the hold inserted deleted when the save has none — one `UPDATE` / `DELETE` per row with
     `corestack_exec_command`, then `bin/magento cache:flush` — and prove the effective value per scope as at step 7 of `migrate-magento` equals the old store's; Shopware 6 — read the old shop's own value on the old host, `bin/console system:config:get
     core.mailerSettings.disableDelivery --format=json` (step 1 of `migrate-shopware`; normally `null` or `false`), then put exactly that
     value back on the target, in `htdocs`, with `corestack_exec_command`:
     ```sh
     bin/console system:config:set core.mailerSettings.disableDelivery false --json   # the old shop's value: false, true or null
     bin/console system:config:get core.mailerSettings.disableDelivery --format=json   # must answer the same value
     ```
     Always with `--json`: without it `false` is stored as the string `"false"`, which Shopware's `MailSender` reads
     as delivery off, so the shop would stay silent; `null` removes the key, as an unset shop had it. Then move DNS:
     with Cloudflare connected, `corestack_domains_point_dns {site_id, hosts, confirm_replacements?}` (the row's own
     production hosts); otherwise the person points the domain's A / AAAA records (or CNAME) at the ingress address the
     facts give. The certificate issues once DNS points.
   - **b. not attached (strategy 1, or no pre-DNS test):** Magento 2 first: put back `env.php`'s own `smtp/disable`
     locks and the database's saved values at every scope as in 9a (the attach's mail step sets only the database's
     default to `0`, which a lock left at `1` would override and which leaves a website or store row the hold set at
     `1`); after the attach, put back the saved default once more if the source's own default was `1`, and prove every
     scope as in 9a. Shopware 6 first: put back the old shop's own
     `disableDelivery` exactly as in 9a (the value read on the old host, `--json`, read back) — a Shopware go-live has
     no mail step, so the attach would leave the hold of step 8 of `migrate-shopware` on — while the row is still a preview,
     whose `MAILER_DSN` is the preview Mailpit, so nothing the copy sends before the attach reaches a real
     recipient. Then `corestack_site_attach_domain {…, point_dns: true}` with Cloudflare connected, or without
     `point_dns` once the person has pointed the records — an ordinary attach: it sets the URLs (a no-op after the
     final import), releases Magento's mail and switches the site's Scheduled tasks on (the built-in line stays off
     until step 10).
   Either way, `corestack_domains_check_dns` until the domain resolves to the ingress. (The URL change,
   `corestack_url_change_apply`, is for moving a live site from one domain to another — never part of a migration.)
10. **Release the remaining holds — mail first.** Queued and scheduled work sends real mail the moment it runs, and a
    v3 production row drops every send until a sending domain exists,
    so nothing is released before the intended mail transport works:
    - **Mail:** if the site sends mail through the platform, `corestack_email_enable` and wait for its task, apply its
      DNS records (`corestack_email_apply_dns` with Cloudflare connected, else the person adds them), then
      `corestack_email_verify` until `corestack_email_get` reports `verified`, and `corestack_email_send_test` arrives;
      on a multi-store Magento 2 site, read `store_mapping` in `corestack_email_get`: a store whose From domain has no
      sending domain of its own (its `warn` is `no_domain`) gets one with `corestack_email_domain_add` (the same DNS, verify and
      test steps, with its `sending_domain`), so each store's mail goes out through its own domain;
      if it sends through its own provider instead (a WordPress SMTP plugin the person wants back, a Laravel or Magento
      SMTP setting), turn that on and prove one test message from the application. While it is not ready, every hold
      stays: tell the person, and wait.
    - **Then the queue consumers** on Magento 2, Laravel and Shopware — `corestack_site_copy_hold_set {site_id,
      consumers: false}` — so the work the final dump carried runs now, once, on the live target;
    - **then** `corestack_crons_get`, `corestack_crons_update` with its `version`, `enabled: true`, `builtin_enabled:
      true` (every platform; false only when rule 19 carried the platform's own job as an entry on its old schedule)
      and the old host's own jobs the person approved switched on (rule 19); WooCommerce: delete
      the target's hold file (`corestack_exec_command`: `rm wp-content/mu-plugins/000-corestack-target-hold.php`);
    - then Shopware's apps step (step 13 of `migrate-shopware`: `bin/console app:shop-id:change move-shop-permanently`
      on 6.7 and later, `bin/console app:url-change:resolve move-shop-permanently` on 6.6).
11. **Verify** on the live domain: `corestack_site_smoke_test`, then `corestack_logs_query` for errors since the
    switch. Keep the old host in maintenance — it is the way back.
12. **Done:** tell the person: the old host stays in maintenance with its crontab commented out until they retire it;
    a Git-mode site is still manual until they switch it back; rule 12's clean-up.

### Rollback
- **Through the Control Panel's own rollback** (a row the Control Panel switched over, within 14 days of going live): read
  `corestack_migration_site_rollback_preview` first. Its `zone_ssl` names each Cloudflare zone SSL/TLS mode the switch
  raised and whether it may be put back; ask the person which of the offered zones to put back, then
  `corestack_migration_site_rollback` with `restore_ssl_zones` set to the names they agreed to (an empty list for none).
  Leaving it out while a zone is offered is refused (`zone_ssl_restore`). A zone another site has since been switched
  into is never offered, and the preview says so.
- **Before DNS moved** (nothing public changed): take the old host out of maintenance (WordPress: delete
  `wp-content/mu-plugins/000-corestack-move-hold.php`; `bin/magento maintenance:disable`; `php artisan up`;
  `bin/console sales-channel:maintenance:disable --all`), restore its crontab from the saved file (`crontab
  ~/crontab.before-corestack.<stamp>`) and let the person start the queue workers again that they stopped at the cutover's step 6 — the
  queued work the final dump also carried then runs there, once, because the target's consumers stay held. The target
  stays as it is — holds on — for another attempt.
- **After DNS moved** — clients may still reach the target for a while (resolver caches, open connections, webhooks,
  its own jobs), so **freeze the target before anything is copied back**:
  1. **Freeze, with no bypass:** `corestack_site_copy_hold_set {site_id, consumers: true, web: true}` and wait for its
     task — the platform's 503 to **every** client, the office address included, and no queue consumer or cron entry
     launched; then Scheduled tasks off (`corestack_crons_update` with `enabled` and `builtin_enabled` false). Not `corestack_maintenance_mode_set`: its flag lets the office address through, so a client there could still write after the freeze. Webhooks are refused and
     retried later by their senders.
  2. **Drain — proven by the hold, not by looking:** the hold's task completes only once no request is in flight
     (php-fpm and nginx both quiet, its `web_drain` `fpm_nginx`; where the site's php-fpm has no status listener,
     nginx quiet and the site's longest allowed request time passed, `web_drain` `nginx`, which takes longer),
     the queue container's drain stamp names the hold (no consumer mid-message — the consumers run in their
     own container, which an exec in `cli-production` cannot see) and no cron invocation is running; a drain
     that cannot finish fails the task with the hold kept, and you wait and call again. Delayed and failed messages
     stay in the queue tables and travel back in the reverse dump — never wait for the tables to be empty: on the old
     host they run once its consumers resume after the reopen (step 5), exactly once, because the target's consumers
     stay held.
  3. **DNS back:** point the domain at the old host again (the person, or the Cloudflare zone's own records), and keep
     the target frozen until `corestack_domains_check_dns` no longer shows the ingress and one old TTL has passed
     after that.
  4. **Copy back** what the target took since the switch — **behind a hold on the old host that does not depend on its
     database**, because the reverse import drops and refills the old host's tables while DNS already points at it:
     Shopware keeps its maintenance flag in the database (`sales_channel.maintenance`, step 5), and the target's dump
     carries it cleared (step 8); WordPress answers its installer while `wp_options` is missing (`wp_not_installed()`
     runs before must-use plugins load, so the move hold does not cover that window).
     - **The entry-point hold** on the old host, before the import: keep a copy of the file every web request loads
       before the database — WordPress `wp-config.php`, Laravel and Shopware `public/index.php`, Magento
       `pub/index.php` — then insert the guard **after** the opening `<?php` tag and any leading `declare(…);`, never
       above them: PHP refuses a file whose `declare(strict_types=1)` is not its first statement, and Shopware 6.7's
       stock `public/index.php` begins with one, so a guard prepended at the very top would be a fatal error, not a
       503. Insert it with PHP itself and lint the result before anything else happens:
       ```sh
       # on <old>, in <old-root>; <entry> = wp-config.php | public/index.php | pub/index.php
       stamp=$(date -u +%Y%m%dT%H%M%SZ); cp -p <entry> ~/entry.before-corestack.$stamp
       php -r '$f = $argv[1]; $s = file_get_contents($f);
         $g = "if (PHP_SAPI !== \"cli\") { http_response_code(503); header(\"Retry-After: 600\"); exit; }";
         $n = preg_replace("/\\A(<\\?php\\b(?:\\s+|\\/\\/[^\\n]*\\n|#[^\\n]*\\n|\\/\\*.*?\\*\\/)*(?:declare\\s*\\([^)]*\\)\\s*;)?)/s", "\\1\n$g\n", $s, 1, $c);
         if ($c !== 1) { fwrite(STDERR, "STOP: the entry point does not start with <?php\n"); exit(1); }
         file_put_contents($f, $n);' <entry> \
         && php -l <entry> \
         || { cp -p ~/entry.before-corestack.$stamp <entry>; echo 'STOP: the guard could not be inserted safely' >&2; false; }
       ```
       then check from outside (step 5's `curl`, answering 503) before the import starts. A lint failure puts the file
       back and stops the rollback (tell the person). CLI tools (WP-CLI, `bin/magento`, `artisan`, `bin/console`) and
       the import are unaffected.
     - **Shopware also:** on the frozen target, `bin/console sales-channel:maintenance:enable --all` before the
       export, so the reverse dump carries the flag set and the old shop is still in maintenance when the guard comes
       off; it is cleared on purpose at step 5.
     - Then `corestack_db_export` of the target (taken after the drain, so it is final; it keeps the queue rows),
       imported on the old host; uploads written since the switch copied back with the reverse of rule 4's path A or B.
       **Verify** before reopening — through the CLI or SQL, never the web, which the guard holds: the newest order,
       user and upload on the old host match the target's (read both with the same query).
  5. **Reopen the old host**: restore the entry-point file from its copy, then as before DNS moved (the move hold, the
     platform's maintenance, `bin/console sales-channel:maintenance:disable --all` on Shopware), restore its crontab,
     and let the person start the queue workers again that they stopped at the cutover. The target stays frozen — copy hold on,
     Scheduled tasks off — until the person retries or deletes it. Keep the window between the switch and a rollback
     short so there is little to carry back.
- **Target damaged by an import:** `corestack_restore_create` from the import's safety snapshot.

