In this section · 10 articles

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

  1. Sign in as a super admin. System Upgrade opens.

  2. Check the two versions: Installed version is what your database records, and Code version is what's on the server.

  3. Select Start upgrade. The button reads Upgrading… while it runs.

  4. 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
  5. 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.