Skip to main content
Version: 6

Upgrading

Backup Your Installation

Before attempting any upgrade or making any changes to your installation, you should always back up your files and database. If properly configured, Blesta can back up your database automatically, but you should perform a manual backup of everything before proceeding.

Upgrading to 6.0?

6.0 introduces several changes that affect upgrades from 5.x: PHP 8.2+ is required, the database is converted to utf8mb4, the cache directory moves above the docroot, and the admin UI is rebuilt on Bootstrap 5 (Paradigm) with the legacy default template removed. Review the v6 Migration Guide before running the upgrade.

Upgrading Blesta​

Watch the video or follow the steps below to upgrade Blesta on your server.

1. Make sure you have valid Support & Updates.​

If you have an active monthly license, or a Blesta Owned Lifetime license, your Support & Updates are valid. If you have an Owned Branded or Owned Unbranded license, check the System Status widget on the Dashboard of your Blesta installation. It should show when your Support & Updates are good through. If they have expired, log into your account at https://account.blesta.com/client/login and click the Manage button next to your license, Addons on the left, and select and purchase Support & Updates.

2. Download Blesta​

Visit https://account.blesta.com/ and click "Downloads", then click to download the latest version. The latest full version is also normally displayed on the home page of https://www.blesta.com.

3. Unzip the Archive​

Unzip the Blesta archive (.zip) file using your favorite compression utility. On Windows, right click and select "Extract All". If the zip is uploaded to or downloaded directly to a Linux server, run the following in your shell:

unzip blesta-x.x.x.zip

4. Upload Files & Launch Upgrader​

Upload the contents of the blesta directory to your server where you installed Blesta overwriting your existing files and point your web browser to ~/admin/upgrade

Blesta may be upgraded in one of two ways:

  • Click the link "Continue with Upgrade" to start the upgrader. OR
  • In a shell, copy and run the command displayed, or cd to the directory you uploaded the contents of blesta, run the following command, and follow the directions to complete installation:
php ./index.php admin/upgrade

As of 6.0, the CLI upgrader accepts an optional flag to skip the interactive confirmation prompt — useful for scripted/automated upgrades:

# Auto-confirm; no prompt
php ./index.php admin/upgrade -y
# or equivalently
php ./index.php admin/upgrade --confirm

Run php ./index.php admin/upgrade -h to view all options.

Patching an Existing Install​

Periodically we release patches that contain incremental changes to the installation files. Patches are released to address bugs or security vulnerabilities. A patch increments the last number in the version, for example 3.0.1, where the "1" is a patch from 3.0.0.

On Patches

Patches can only be applied to the minor version of Blesta. A patch for say 5.12.2 can only be applied to 5.12.x. If you are upgrading to a major or minor release, use the full version instead. major.minor.patch

Follow these steps to apply an incremental patch.

1. Download the Patch​

Visit https://account.blesta.com/client/plugin/download_manager/client_main/index/ and click "Patches", then click the patch for your release.

2. Unzip the Archive​

Unzip the Blesta archive (.zip) file using your favorite compression utility. On Windows, right click and select "Extract All". If the zip is uploaded to or downloaded directly to a Linux server, run the following in your shell:

unzip blesta-x.x.x-x.x.x.zip

3. Upload Files & Launch Upgrader​

Upload the contents of the blesta directory to your server where you installed Blesta overwriting your existing files and point your web browser to ~/admin/upgrade.

Look in the footer for "Installed Version" to confirm that the patch was applied, and the new version is recognized.

That's it!

What changes during the upgrade to 6.0​

The upgrade to 6.0 performs several behind-the-scenes changes you should be aware of:

Database character set conversion to utf8mb4​

The 6.0 upgrade detects any tables or columns still using a non-utf8mb4_unicode_ci collation and converts them in place. New installs use utf8mb4 from schema.sql, so this step is a no-op for those.

If you have customizations or extensions that defined columns with a different collation, those will be converted as part of this step. If the upgrade fails with a "Specified key was too long" error, see the Errors During Upgrade section below.

Cache directory moves above the document root​

In 6.0, the cache directory moves from public_html/cache/ to a cache_blesta/ directory above your docroot. The upgrader:

  1. Creates cache_blesta/ next to your uploads/ directory (one level above docroot).
  2. Copies existing cache contents into it.
  3. Writes a deny-all .htaccess to the new location.
  4. Updates the cache_dir setting and writes a marker file under config/.

If your installation uses custom file permissions, a chrooted environment, or symlinks that constrain access above the docroot, verify the new path is writable before upgrading. Admins who have hardened open_basedir may need to add the new path to their open_basedir allow list.

Signed release manifest​

6.0 releases ship with a manifest.json file at the root of the installation, containing the list of core files and their SHA-256 checksums. The manifest is signed with Blesta's release key. No action is required during a normal upgrade — the manifest enables the new system integrity check feature, which can detect modifications to core files after install.

Composer v2​

Blesta 6.0 moves to Composer v2 and includes composer.lock in the distribution (it is no longer git-ignored). If you maintain extensions and vendor dependencies via Composer, you will want to ensure your Composer is at least v2.x and that your extension's composer.json is updated accordingly.

Failed Upgrade​

If running /admin/upgrade does not complete all the database migrations, things may not work correctly and it may be necessary to modify a migration task so that it picks back up where it failed. The first step is to determine what the last completed migration version was. To find out, run this query:

SELECT `value` FROM `settings` WHERE `key`='database_version';

As an example, let's say this returns: 4.4.0-b1 but you uploaded the files for 4.6.0. Please note that there is not a direct correlation between the database version and the version of Blesta you are running. If your database says 4.4.0-b1 you could be running 4.4.2 if there were no database changes between 4.4.0-b1 and 4.4.2.

Next, look at the migration tasks in /components/upgrades/tasks/, you'll see files like this:

upgrade4_3_0_b1.php
upgrade4_4_0_b1.php
upgrade4_5_0_b1.php
upgrade4_6_0_b1.php
upgrade4_6_0.php
upgrade4_7_0_b1.php

The version in the filename corresponds to the version in your database. If your database shows 4.4.0-b1, then the last migration task it fully completed was upgrade4_4_0_b1.php. This means that when it tried to run the next migration, upgrade4_5_0_b1.php one of the tasks in that file failed. Errors that you are getting in your logs may help identify which task failed, but lets look at upgrade4_5_0_b1.php because we know something in that file failed. Edit the file in your favorite text editor, that will not modify the file encoding (UTF-8) or line endings. Look for the function tasks() and the methods listed within.

public function tasks()
{
    return [
        'addProxySetting',
        'updateInvoiceTerms',
        'addPackageNames',
        'addPackageDescriptions',
        'addPackageGroupNames',
        'addPackageGroupDescriptions',
    ];
}

In the example above, we can see that the following tasks are run in order to upgrade to 4.5.0-b1:

  • addProxySetting
  • updateInvoiceTerms
  • addPackageNames
  • addPackageDescriptions
  • addPackageGroupNames
  • addPackageGroupDescriptions

If addProxySetting has already ran, then we can comment it out and run /admin/upgrade again in our browser. Then, check your database version again. If it's not at least 4.5.0-b1, then we may need to comment out the next task, updateInvoiceTerms and run /admin/upgrade again and check the database version again. Continue commenting out tasks ONE at a time and running /admin/upgrade until the upgrade is able to complete and shows the version of the most recent file in /components/upgrades/tasks/

Here's an example of a commented out task:

public function tasks()
{
    return [
        //'addProxySetting',
        'updateInvoiceTerms',
        'addPackageNames',
        'addPackageDescriptions',
        'addPackageGroupNames',
        'addPackageGroupDescriptions',
    ];
}

Errors During Upgrade​

Error: PDOException - Specified Key Too Long​

Error Message​

During an upgrade, the following error was encountered:

PDOException: SQLSTATE[42000]: Syntax error or access violation: 1071 Specified key was too long; max key length is 767 bytes in /var/www/html/vendors/minphp/db/src/PdoConnection.php:196
Solution​

This error occurs when the collation is updated from utf8 to utf8mb4 when a varchar 255 field has more than 767 bytes. In MySQL 5.7.7 and MariaDB 10.2.2, this value was increased to 3072 bytes. We would recommend upgrading your database and re-attempting the upgrade. As an alternative, you can try running this query prior to re-attempting an upgrade:

SET @@global.innodb_large_prefix = 1;

Error when upgrading through 5.8.0-b1: SQLSTATE[22004]: Null value not allowed​

Error Message​
SQLSTATE[22004]: Null value not allowed: 1138 Invalid use of NULL value in /vendors/minphp/db/src/PdoConnection.php:196 Stack trace: #0 /vendors/minphp/db/src/PdoConnection.php(196): PDOStatement->execute(Array) #1 /components/upgrades/tasks/upgrade5_8_1.php(87): Minphp\Db\PdoConnection->query('ALTER TABLE `co...') #2 /components/upgrades/tasks/upgrade5_8_1.php(54): Upgrade5_8_1->setContactPermissionClientId() #3
Solution​

This error may occur when running the setContactPermissionClientId task in /components/upgrades/tasks/blesta5_8_1.php to solve:

  • Comment out the setContactPermissionClientId task in the upgrade file.
  • Run the following query on your database to resolve any orphaned records (BACKUP FIRST).
DELETE contact_permissions.* from contact_permissions left join contacts on contact_permissions.contact_id = contacts.id where contacts.client_id is null;
Last updated on