Upgrading

A new release replaces the core code. It must not touch what belongs to your installation: your settings, your data, your plugins, your themes and your tenant templates. This page says where each lives and how to upgrade without losing them.

What survives

What	Where	On upgrade
Settings and secrets	apps/backend-laravel/.env	Kept. Compare it with the new .env.example for new variables
Data	The database and object storage	Kept. Migrations change the schema, and don't drop data
Your plugins	apps/backend-laravel/plugins/<slug>/	Never touched by a release
Your themes	apps/backend-laravel/themes/<slug>/	Never touched by a release
Tenant templates and theme choices	The database	Kept
Uploaded files and PDFs	Object storage	Kept
Bundled example plugins and themes	bundled-plugins/, bundled-themes/	Replaced by the release

Themes and tenant templates are Twig templates. Your own theme files live in themes/, and a tenant's own templates are stored per business and run in a sandbox. Neither is part of the core code, so a release doesn't overwrite them. See themes and document templates.

If a slug exists in both a customer folder and a bundled folder, the customer folder wins. To change a bundled example, copy it into plugins/ or themes/ and edit the copy. If you edit the bundled copy in place, a release will overwrite your edits.

Anything under app/ that you edited directly will be overwritten or will conflict. Move customisations into a plugin or theme. See extending.

Before you upgrade

1. Read the release notes, if any came with the release, for new variables, queue names or breaking changes.
2. Take a database backup and check you can restore it. See backup and restore.
3. Try the upgrade on a staging copy first, with a copy of the production database.
4. Check APP_KEY is backed up.

Upgrade steps

1. Put the new release's backend and built console in place, keeping .env, storage/, plugins/ and themes/. See deploy.
2. Compare .env with the new .env.example and add any new variables.
3. Install dependencies: composer install --no-dev --optimize-autoloader.
4. Run migrations: php artisan migrate --force. This also runs pending migrations for plugins you've installed.
5. Clear caches: php artisan optimize:clear.
6. Run php artisan rangefront:plugin:list. Look for any plugin marked as needing another core version or failing to load.
7. Restart Horizon and Reverb, and reload php-fpm.
8. Check the install checks.

Plugins and compatibility

Each plugin declares the core versions it supports in requires.core in its plugin.json. A plugin that doesn't match the new core version is listed as incompatible and isn't loaded, so it can't break the upgrade. Admin > Plugins shows "Needs core X" for it. Update the plugin, or its requires.core once you've tested it.

Hook names are a stable contract. They aren't renamed or removed without a major version, so a plugin that listens to a hook keeps working across minor releases. A hook listener that throws is logged and skipped, so one broken plugin doesn't stop a job being completed or an invoice being sent. In development, set EXTENSIBILITY_RETHROW=true to see the error.

Plugin data is kept when a plugin is switched off or uninstalled. Only rangefront:plugin:uninstall --purge deletes it.

Permissions after an upgrade

New releases add permission keys. Migrations grant them to roles in existing businesses where it makes sense. Check each role's checklist after upgrading. The console role editor doesn't list every permission yet; see users and roles.

The contract and the field app

If a release changes the API, regenerate the contract and types when you build (npm run contracts:generate). Field phones may be running an older app build. Update the app, and check a test phone syncs after the upgrade.

Rolling back

Put the previous release's files back, restore the database backup taken before the upgrade, clear caches and restart Horizon and Reverb. Rolling back without restoring the database is only safe if the release ran no migrations.