shc adapter migrate

run a data migration (adapted app -> native SHC app) off a dumb backup

Synopsis

Transpile an adapted app’s DUMB backup (crash-consistent source volumes) into its native SHC target(s). The app’s *.migration.yaml resolves the target set for its version; each target’s transform runs in a one-off container with the SOURCE volumes mounted READ-ONLY, producing that target’s conforming .bak; the per-target artifacts are then assembled into a consistency GROUP (.bkg) the restore machinery consumes.

—from takes one of THREE source shapes: a dumb-backup directory whose immediate subdirectories are the source volumes (subdir name = logical volume name); /[@] a stack SHC already runs (an adapted app going native): the stack is paused, its named volumes are copied into a dumb backup, and it resumes. The adapter recorded at load time (compat.adapter in the stack’s app.yaml) is cross-checked against —adapter; ssh://[user@]host a live foreign platform box: the app’s data volumes are pulled straight into a local dumb backup (no package transpile). The box app id is ; pass —source-app when the platform names it differently (portainer names every app by CONTAINER, e.g. wpstack-wordpress-1).

Runs IN-PROCESS on the node it is invoked on: it needs docker and the source volumes on local disk. —dry-run resolves + validates + plans and produces nothing; —emit-only runs the transforms but leaves the .bak artifacts loose and EMITS the shc recover command instead of a .bkg.

shc adapter migrate <app> --adapter <name> --version <ver> --from <src> [flags]

Examples

  shc adapter migrate erpnext --adapter runtipi --version 14.2.3 --from ./dump
  shc adapter migrate linkwarden --adapter runtipi --version 2.15.1 --from default/linkwarden
  shc adapter migrate linkwarden --adapter runtipi --version 2.15.1 --from default/linkwarden@prod
  shc adapter migrate linkwarden --adapter runtipi --version 2.15.1 --from ssh://root@10.0.0.5
  shc adapter migrate wordpress --adapter portainer --version 6.5-apache --from ssh://root@10.0.0.5 --source-app wpstack-wordpress-1
  shc adapter migrate erpnext --adapter runtipi --version 14.2.3 --from ./dump --dry-run

Options

      --adapter string               adapter the adapted app came from (caprover|casaos|cloudron|coolify|dockge|dokploy|easypanel|kube|portainer|runtipi|synology|truenas|umbrel|unraid|yunohost) [required]
      --apps-root string             app catalog root holding <targetApp>/migrations/<adapter>.migration.yaml (default ./apps when present, else <base>/apps — the catalog-shipped recipes)
      --box-app string               on-box app id for the ssh:// source when it differs from <app> (e.g. coolify keys installs by resource uuid, not the app name); <app> still names the recipe source app
      --dry-run                      resolve + validate + plan the transforms; run nothing, write nothing
      --emit-only                    run the transforms but leave the .bak artifacts loose; emit the recover command instead of a .bkg
      --from string                  source: a dumb-backup directory, <tenant>/<name>[@<env>] (a stack SHC runs), or ssh://[user@]host (a live foreign platform box)
  -h, --help                         help for migrate
  -i, --identity string              ssh private key file for the ssh:// source (agent + password are also tried)
      --insecure-host-key            skip ssh host-key verification for the ssh:// source (lab / one-shot migrations only)
      --known-hosts string           known_hosts file for ssh:// host-key verification (default ~/.ssh/known_hosts)
      --no-quiesce                   do not pause the source stack/app before copying its volumes (accepts a live copy)
      --out shc backup group --out   destination .bkg group path (default <work-dir>/<group>.bkg) — matches shc backup group --out
      --password string              ssh password for the ssh:// source (also decrypts an encrypted --identity)
      --source-app string            id of the app on the ssh:// box when it differs from <app> (e.g. a portainer per-container name like wpstack-wordpress-1); defaults to <app>
      --version string               adapted app version — resolves the migration's target set [required]
      --work-dir string              directory the per-target artifacts + group are written to (default ./migrate-<app>)

Options inherited from parent commands

      --config stringArray   extra YAML config file to layer on top of auto-discovered config; repeatable, later files win
  -d, --debug                enable debug mode (default: $SHC_DEBUG)
  -e, --environment string   environment name (default: $SHC_ENVIRONMENT)
      --exclude string       comma-separated dotted paths to drop
      --fields string        comma-separated columns/keys to show (and their order)
      --filter string        comma-separated dotted paths to keep (drops everything else)
  -o, --output string        output format: tty|text|json|yaml (default: $SHC_OUTPUT)
  -s, --stack string         stack name (default: $SHC_STACK)
  -t, --tenant string        tenant name (default: $SHC_TENANT)
  -v, --verbose              verbose output (default: $SHC_VERBOSE)

shc adapter migrate