Backup and restore your Vulpy Commerce shop

Snapshot environments with pnpm vulpy env backup, migrate data from a local dev machine to a VPS, and restore on demand from a bundle archive.

Vulpy Commerce persists everything under .data/ in the project folder, so backup and restore are file-level operations wrapped by CLI commands. This page covers per-environment snapshots and the local-to-VPS migration flow.

Ask Fox to draft the backup and migration commands. Fox knows what a backup includes and can spell out the exact tar and rsync for you.

Try prompts like:

• “Explain what a backup includes.”
• “Draft the migrate-from-laptop command sequence for me.”
• “What’s the safest way to restore Payload media only?”

Environment backups

Every environment has a matching pair of commands.

Backup

pnpm vulpy env backup <name>

Use these against dev, staging, or live. Backups include configuration (per the app contract) and the environment’s persistent data.

Fox cannot run these commands. Backups and restores are host-scope operations that you run as the deploy user (sudo -iu vulpy-commerce).

Migrate from local dev to a VPS

If you have been developing on your laptop and want to move data onto a fresh VPS install, use the migrate bundle scripts.

1. Export on your laptop

   ./scripts/migrate/export-local.sh
   

   This writes a bundle under .tmp/migrate-bundle-*.tar.gz.

2. Copy the bundle to the VPS

   scp .tmp/migrate-bundle-*.tar.gz user@vps:/opt/<project-name>/
   scp deploy/.env user@vps:/opt/<project-name>/deploy/.env
   
3. Sync the working tree (optional)

   If you also want the code from your laptop, exclude regenerable artifacts:

   rsync -aH \
     --exclude='node_modules' \
     --exclude='.next' \
     --exclude='.medusa' \
     --exclude='.turbo' \
     --exclude='.tmp/migrate-bundle-*' \
     ./ user@vps:/opt/<project-name>/
   ssh user@vps 'cd /opt/<project-name> && pnpm install'
   
4. Import on the VPS

   cd /opt/<project-name>
   COMPOSE_SUDO=1 ./scripts/deploy/rollout-vps.sh migrate-bundle-YYYYMMDD.tar.gz
   

Seed-first deploys

For an empty-DB rollout that seeds on start instead of importing a bundle, set two variables before the rollout:

SEED_ON_START=1
SYNC_PUBLISHABLE_KEY=1

The --seed install flag sets both automatically.

Restore replaces data. Take a fresh pnpm vulpy env backup <name> before restoring anything into a live environment so you can roll back.

Environments

How dev, staging, and live are isolated on disk.

Troubleshooting

Common issues and the exact commands to fix them.