Upgrade a Vulpy Commerce shop safely

Pull new Vulpy Commerce releases, rebuild containers, run migrations, and roll back with backups if a release breaks staging.

Upgrading Vulpy Commerce means pulling a new release, rebuilding containers, and verifying that the shop still works. Always test upgrades in staging before touching live.

Ask Fox for the upgrade plan. Fox reads the changelog and your env, tells you what will rebuild, and drafts the staging-first sequence.

Try prompts like:

• “Draft an upgrade plan for staging.”
• “Explain what will rebuild if I change REQUIRE_LOGIN_FOR_PRICES.”
• “Diff my current env against the new default .env.example.”

Test in staging first

Every upgrade should run through staging with a copy of live data. Staging is an isolated Docker Compose project with its own .env and .data/ directory, so a failed upgrade there cannot harm production.

For environment setup, see Environments.

Upgrade flow

1. Take a fresh backup

   Before changing anything, back up the environment you are upgrading:

   pnpm vulpy env backup <name>
   
2. Pull the new release

   Update your checkout to the latest release:

   git pull
   
3. Install dependencies

   Pick up any new or updated packages:

   pnpm install
   
4. Rebuild images if needed

   If bake-time environment variables changed (for example, REQUIRE_LOGIN_FOR_PRICES), rebuild the images so the new values are baked in. For a full list of bake-time variables, see Environment variables.

5. Restart the environment

   Bring the environment down and back up:

   pnpm vulpy env down <name>
   pnpm vulpy env up <name>
   
6. Run migrations

   Medusa migrations run automatically on container start. Payload migrations also run on start. Confirm both complete without errors in the logs.

7. Verify

   Run health checks to confirm the upgrade succeeded:

   pnpm vulpy verify
   pnpm vulpy env status <name>
   

Rollback

If verification fails, restore from the backup you took before starting:

pnpm vulpy env restore <name> <archive>

This restores the database and data directory to the pre-upgrade state. For more details, see Backup and restore.

Upgrade Fox

Fox upgrades are separate from environment upgrades:

pnpm vulpy hermes down
git pull
pnpm vulpy hermes up
pnpm vulpy hermes doctor

The doctor command confirms the Tailscale sidecar, host egress lock, and IMDS lock are still healthy after the Fox restart.

Never upgrade live without first upgrading staging with the same data. Restore a live backup into staging if you need identical conditions.

Bake-time environment variable changes need an image rebuild. Just restarting containers will not apply them. If you changed a bake-time variable, rebuild before bringing the environment up.

Backup and restore

Create and restore backups before and after every upgrade.

Logs and health

Tail logs and run health checks to spot upgrade issues early.