Upgrading the Platform

CarphaCom uses release directories so upgrades are atomic and rollback is fast.

Check for available platform updates

curl -fsSL https://carphacom.com/api/platform/latest

Returns:

{
  "latest": "1.4.2",
  "current": "1.4.0",
  "changelog": "https://carphacom.com/changelog/1.4.2",
  "breaking": false
}

The admin dashboard also shows an Update available banner when a new version is published.

Pre-upgrade checklist

1. Take a fresh backup (see Backups & Restore).
2. Read the changelog. Look for breaking changes, schema changes, plugin compatibility notes.
3. Check installed plugins: are they compatible with the new platform version? Plugin manifests declare carphacom_min_version — they may also have carphacom_max_version.
4. Schedule a maintenance window if breaking changes apply (typically only major version bumps).

Run the upgrade

sudo carphacom-upgrade --to 1.4.2

What this does:

1. Downloads the new release tarball, verifies its signature.
2. Extracts to /opt/carphacom/releases/<timestamp>_v1.4.2/.
3. Runs npm ci in each subdirectory.
4. Runs database migrations (npx medusa db:migrate).
5. Builds admin and storefront (npm run build).
6. Atomically swaps the current symlink to the new release.
7. Reloads PM2 with pm2 reload all --update-env.
8. Probes /health on each service. If any fails, rolls back automatically.

Rollback

If something goes wrong after the upgrade window:

sudo carphacom-rollback

Switches current back to the previous release. Does not roll back database migrations — some migrations are forward-only. Use a database backup if you need to roll back schema.

Plugin updates

Plugins update independently of the platform via Marketplace → Updates. After a platform upgrade, check this tab and update any plugins flagged as compatible with the new version.

Major version upgrades

For major bumps (e.g. 1.x → 2.0):

1. Test in a staging environment first (clone production data to a separate VM).
2. Read the migration guide in the changelog.
3. Schedule downtime — major upgrades may take 30–60 minutes for large databases.
4. Have your backup ready and verified.

Automation

You can opt into auto-upgrades for patch versions only (e.g. 1.4.0 → 1.4.x):

In admin → Settings → Platform → Auto-upgrade, toggle Patch versions only.