> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulpy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tip>
  **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`."
</Tip>

## 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](/deploy/environments).

## Upgrade flow

<Steps>
  <Step title="Take a fresh backup">
    Before changing anything, back up the environment you are upgrading:

    ```bash theme={null}
    pnpm vulpy env backup <name>
    ```
  </Step>

  <Step title="Pull the new release">
    Update your checkout to the latest release:

    ```bash theme={null}
    git pull
    ```
  </Step>

  <Step title="Install dependencies">
    Pick up any new or updated packages:

    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="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](/reference/env-vars).
  </Step>

  <Step title="Restart the environment">
    Bring the environment down and back up:

    ```bash theme={null}
    pnpm vulpy env down <name>
    pnpm vulpy env up <name>
    ```
  </Step>

  <Step title="Run migrations">
    Medusa migrations run automatically on container start. Payload migrations also run on start. Confirm both complete without errors in the logs.
  </Step>

  <Step title="Verify">
    Run health checks to confirm the upgrade succeeded:

    ```bash theme={null}
    pnpm vulpy verify
    pnpm vulpy env status <name>
    ```
  </Step>
</Steps>

## Rollback

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

```bash theme={null}
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](/deploy/backup-restore).

## Upgrade Fox

Fox upgrades are separate from environment upgrades:

```bash theme={null}
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.

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

<Warning>
  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.
</Warning>

<CardGroup cols={2}>
  <Card title="Backup and restore" icon="database" href="/deploy/backup-restore">
    Create and restore backups before and after every upgrade.
  </Card>

  <Card title="Logs and health" icon="activity" href="/deploy/logs-health">
    Tail logs and run health checks to spot upgrade issues early.
  </Card>
</CardGroup>