Run a system upgrade
After new Laramin Core code is deployed, run the System Upgrade to apply its database migrations, migrate your enabled modules and record the new version.
- Applies to
- Core 12.0 and later
- Who can do this
- Platform owner
- Where
- System Upgrade (opens by itself when an upgrade is waiting)
On this page
Before you start
- Only super admins can run the upgrade. Other users can see the screen, but the upgrade won't run for them.
- The new Core code must already be on the server. The System Upgrade doesn't download anything. It brings your database up to the code that's installed.
- Back up your database.
- For a major version, read the upgrade notes that ship with the release (
UPGRADE.md) before you start. Upgrade Core first, then your add-ons.
When it appears
Laramin compares the version recorded in your database with the version of the code on the server. While the code is newer, every admin page sends you to System Upgrade. You can also open it yourself at /admin/upgrade. When nothing is waiting, that address takes you to the dashboard.
Steps
-
Sign in as a super admin. System Upgrade opens.
-
Check the two versions: Installed version is what your database records, and Code version is what's on the server.
-
Select Start upgrade. The button reads Upgrading… while it runs.
-
Wait while the three steps run in turn. Each one moves from Pending to Running to Done:
- Core database migrations
- Module migrations, for every enabled module
- Reconcile versions & clear caches
-
When all three show Done, select Go to Dashboard.
What happens next
Laramin records the new Core version, plus the version of every module on disk, and clears its configuration, application and view caches. Admin pages open normally again.
A module that's disabled during the upgrade isn't migrated in step 2. Its migrations run when you enable it.
If a step fails
The step shows Failed with the reason, usually Upgrade failed: followed by the error. The steps after it don't run.
- You aren't a super admin. The first step fails. Ask a super admin to sign in and run the upgrade.
- A migration failed. Fix the cause in the error, for example a database permission or a conflict with existing data. Then select Start upgrade again. It starts from step 1 again, and migrations that already ran aren't run twice.
- Module migrations failed. Step 2 tries every enabled module, even after one fails, and then says Migrations failed for: followed by the modules' names. The new version isn't recorded, so you can fix each module's cause and run the upgrade again.
- It keeps failing. Raise a ticket from Support Center, with the step and the exact error. Leave the database as it is until you have an answer.
Careful: While an upgrade is waiting, every admin page sends people to System Upgrade. Plan the upgrade for a quiet time, and finish it in one sitting.
Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.bsscn.com. The online article may have changed since.