Upgrades
Upgrade a self-hosted installation without losing data or plugin compatibility. This guide follows version 3.1.7 (03acdf712c).
Back up first; see Database Migrations. For runtime settings, see Configuration.
1. Choose a compatible image set
CI publishes per-service repositories such as erxes/erxes-next-core-api, erxes/erxes-next-gateway, erxes/erxes-next-ui, erxes/erxes-next-<plugin>_api, erxes/erxes-next-logs, and erxes/erxes-next-automations. A product version such as 3.1.7 is not evidence that every image has a :3.1.7 tag.
- List the images you run (Core UI, gateway, Core API, logs-service, each plugin API, widgets/portal apps).
- Pick tags whose source revisions you have checked together. Prefer explicit version-plus-SHA tags over floating
latestfor rollback. - Record the selected references and digests (
docker images --digests).
The release.yml workflow promotes tested :latest images to :$VERSION; mirror that discipline in your own promotion.
2. Upgrade in staging first
- Restore a production backup to staging.
- Deploy the candidate image set with the production
.envshape (different secrets/hosts). - Run Database Migrations checks, then verify login, enabled plugins, automations, file URLs, and customer-facing apps.
- Load-test the paths you care about before touching production.
3. Upgrade production
- Announce the window and stop scheduled jobs that write during migration if needed.
- Pull the recorded images, recreate the Compose services, and wait for gateway schema composition.
- Verify
/health,/graphql({ __typename }), owner login, and one representative flow per plugin. - Keep the previous image tags and the pre-upgrade database backup until the new version is stable.
4. Roll back if needed
- Recreate services with the previous image tags.
- Restore the pre-upgrade database backup only if the migration changed stored data and forward-fix is riskier. Restoring loses writes made after the backup.
- Re-verify health, GraphQL, and login.
Source references
Was this helpful?
