Migrating a store in from another host

Working draft. How to prepare your store's data on your current host so our Import accepts it. If you're restoring a copy you downloaded from us, you don't need any of this — just upload those files as-is. See exporting-and-importing-your-store-data.md for the overview and encryption-key-and-configuration.md for why your encryption key matters.

Moving a store in from a different host means preparing the three pieces yourself — database, application code, media — each in the format below, then uploading them from your store's Import screen.

Before you start

• Match your Magento version. Set up your destination store on the same Magento version your data came from. A dump from a newer version than the destination is rejected; small differences are reconciled for you.
• Import overwrites the matching part of your store. A backup is taken for you automatically just before the import, so you can roll it back if the result isn't what you expected — but still confirm you're importing into the right store first.
• Order: code and database together with Code + database together (the safer way), then media. One piece at a time? Code first, then database, then media.

1. Database — a SQL dump + your encryption key

Two simple pieces — no special bundle format to build.

a) A SQL dump of your Magento database. A plain, complete dump is all we need:

mysqldump --single-transaction --routines --triggers --no-tablespaces YOUR_DB > database.sql

Upload it however is easiest — the raw .sql, gzipped (.sql.gz), or inside a .zip or .tgz; all are accepted. You don't need to hand-clean it: the import normalizes portability details for you (for example, references to database users from your old host that wouldn't exist on the new one). If your host only offers a "download SQL" button, that's fine as long as it's a full dump.

b) Your encryption key. When you start the database import, the portal shows an "Encryption key" field — paste your key there. Find it in your old store's app/etc/env.php, under crypt → key; copy the whole value (including any newline-separated older keys if you've ever rotated it, or older encrypted data won't decrypt). This keeps encrypted settings — payment credentials and the like — readable after the import, so the import won't proceed without it. See encryption-key-and-configuration.md.

Re-uploading a database copy you downloaded from us? It already carries your key — leave the "Encryption key" field blank.

2. Application code — a .tgz or .zip

A single archive of your Magento directory. Either format works — the import detects it automatically.

• Include everything under your Magento root, including vendor/, so it runs without a rebuild. app/etc/env.php must be present. (If your code lives in version control without vendor/, run composer install first so vendor/ is populated.)
• Exclude these — they're rebuilt for you, or must never be shared: var/, generated/, pub/static/, pub/media/, and auth.json (your Adobe Marketplace credentials — do not include them).

Example with tar (from inside your Magento directory):

tar -czf code-bundle.tgz \
  --exclude=./var --exclude=./generated --exclude=./pub/static \
  --exclude=./pub/media --exclude=./auth.json .

Or make a .zip of the same folder, leaving those paths out — whichever you're comfortable with. Your old env.php's connection details don't matter: we keep your new store's own settings and only bring your code across.

On a Mac? Archive the contents, not the folder. If you download a copy from us, macOS unzips it into a folder on download — and if you then right- click → Compress that folder, the archive wraps everything under an extra top-level folder (plus hidden __MACOSX files), so your files end up one level too deep. Instead, from Terminal, go into the folder and archive its contents: cd your-store-folder && tar -czf ../store.tgz . — that keeps app/, vendor/, etc. at the top. (We tolerate a wrapped folder on import, but a clean archive is smaller and avoids surprises.) The same applies to your media archive below.

3. Media — a .zip or .tgz of your images

Archive your old pub/media — the import accepts .zip or .tgz, and any of these layouts (whichever is easiest):

• a top-level media/ folder, or
• a pub/media/ folder, or
• the media files at the archive root.

# e.g. from inside your Magento root:
tar -czf media-bundle.tgz pub/media        # pub/media/ layout
# or
( cd pub/media && zip -r ../../media-bundle.zip . )   # media tree at the root

Either format and any of those layouts is detected automatically.

Uploading

Import from your store's Import screen: your code and database with Code + database together (the safer way — one maintenance window, and the database is updated by its own code), then your media. If you import one piece at a time, import the code first, then the database — a database imported before its code can lose settings of extensions the current code doesn't have yet.

• Large stores are fine. Uploads are split into chunks and resume if interrupted; the only ceiling is a generous size limit sized to your plan, not any browser or upload-size limit.
• Your store goes into maintenance mode while the import runs, and a backup is taken just before it starts so you have a restore point. After a database or code import it stays in maintenance until you bring it online: let yourself in from the Maintenance tab (Change who can see it…) to check it first.

After importing

A few things are reset for you as part of the import — check each one:

• Your admin login. Your store's main admin account is given a new password during the import (the imported store's admin passwords can't be carried across in a usable form). Find the new password in your portal, under your store's admin login details. Any other admin users from the imported store keep their own passwords.
• Email sending is reset to a safe default. Transactional email (order confirmations, password resets, and so on) is set to send from no-reply@your-domain, and any custom mail-server settings carried in the import are cleared — this stops the imported store's old email configuration from silently breaking your mail. If you'd set up sending from your own branded domain, set it up again after importing.
• Scheduled tasks are turned off. So nothing runs against a half-checked store, your store's scheduled tasks (cron) are switched off after an import. Re-enable them from your portal once you've looked the store over.
• Check your payment methods and any encrypted integrations. If the encryption key was correct, they simply work; if something's unreadable, the key you pasted didn't match the data — re-import with the correct one.
• Indexes and caches are rebuilt for you.
• If the result isn't what you expected, restore the backup taken just before the import (see your Backups tab).