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
- Take a fresh backup (see Backups & Restore).
- Read the changelog. Look for breaking changes, schema changes, plugin compatibility notes.
- Check installed plugins: are they compatible with the new platform version? Plugin
manifests declare
carphacom_min_version— they may also havecarphacom_max_version. - 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:
- Downloads the new release tarball, verifies its signature.
- Extracts to
/opt/carphacom/releases/<timestamp>_v1.4.2/. - Runs
npm ciin each subdirectory. - Runs database migrations (
npx medusa db:migrate). - Builds admin and storefront (
npm run build). - Atomically swaps the
currentsymlink to the new release. - Reloads PM2 with
pm2 reload all --update-env. - Probes
/healthon 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):
- Test in a staging environment first (clone production data to a separate VM).
- Read the migration guide in the changelog.
- Schedule downtime — major upgrades may take 30–60 minutes for large databases.
- 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.