Skip to main content

Update Passbolt on the Virtual Appliance

Prerequisites​

For this tutorial, you will need:

  • A minimal Debian 12 server.
  • Passbolt Debian 12 package installed.

The recommended server requirements are:

  • 2 cores
  • 2GB of RAM

FAQ pages:

Update passbolt​

1. Take down your site​

It is generally a good idea to stop running the site prior to the upgrade. This is to avoid having side effects such as active users corrupting the data in the middle of an upgrade.

sudo systemctl stop nginx

2. Backup your database​

It is recommended to always perform a backup of your passbolt installation. Please check the backup article

3. Upgrade your system​

sudo apt update
sudo apt --only-upgrade install passbolt-pro-server
sudo apt upgrade

4. Clear the cache​

Finally make sure you clear the application cache, to make sure any changes in the database structure are reflected in model cache files:

sudo -H -u www-data bash -c "/usr/share/php/passbolt/bin/cake cache clear_all"

5. Bring your site back online​

Almost done:

sudo systemctl start nginx

6. Troubleshooting​

After the update, the server should automatically ran a dry run of the cleanup to let you know if there is any data integrity issues.

No issues found​

If you see an output that looks like this:

Open source password manager for teams
-------------------------------------------------------------------------------
Cleanup shell (dry-run)
-------------------------------------------------------------------------------
No issue found, data looks squeaky clean!

It means that you don't have any database integrity issues, you can move forward and run the healthCheck!

Issues found​

Open source password manager for teams
-------------------------------------------------------------------------------
Cleanup shell (dry-run)
-------------------------------------------------------------------------------
N issues found in table Y (data integrity message)
N issues detected, please re-run without --dry-run to fix.

Some data integrity issues have been found, to resolve them, you need to re-run the cleanup without the dry run flags:

sudo -H -u www-data bash -c "/usr/share/php/passbolt/bin/cake passbolt cleanup"

You can also run the following command to ensure everything is working properly:

sudo -H -u www-data bash -c "/usr/share/php/passbolt/bin/cake passbolt healthcheck"

The update is blocked by PHP dependencies​

Since passbolt v5.0.0, the passbolt server package requires PHP 8.2 or newer. If the repositories of your operating system release do not provide PHP 8.2, the package manager cannot install the new passbolt version and your instance stays on the last version compatible with your PHP.

The following packages have been kept back:
passbolt-ce-server
0 to upgrade, 0 to newly install, 0 to remove and 1 not to upgrade.

Trying to install the package directly instead fails with E: Unable to correct problems, you have held broken packages.

In this situation, update your server to an operating system release that provides PHP 8.2 or newer, or migrate passbolt to a fresh server running a supported release by following the migration guides.

LDAP synchronisation stops working after the update (Pro Edition)​

Since passbolt v5.12.0, the passbolt server package requires the php-ldap extension on all editions, and the package manager installs it automatically during the update.

On Debian and Ubuntu servers using a third-party PHP repository (such as sury.org or the ondrej PPA), php-ldap is a metapackage that follows the repository default PHP version, which can be newer than the PHP version running passbolt. In that case the update installs the LDAP extension for the wrong PHP version, the ldap_* PHP functions stay missing, and the directory synchronisation fails.

Install the extension matching the PHP version that serves passbolt, then restart PHP-FPM. For example, for PHP 8.2:

sudo apt install php8.2-ldap
sudo systemctl restart php8.2-fpm

If the directory synchronisation still fails after the update, verify the LDAP extension is loaded for the PHP version passbolt runs on before investigating the directory configuration itself.

If you run into some issues​

  • Make a copy or screenshot of the errors messages displayed on the screen
  • Check for error message in the logs directory
  • Check for error message in the browser console
  • Checkout the previous working version using git
  • Drop the database and load your backup data to restore to a previously working version
  • Note down the the details of you environment: your OS, php, MariaDB environment versions.

Where to get help:

  • If you are a Passbolt Pro Edition subscriber send us an email with the details.
  • If you are a Passbolt Community Edition user you can open new thread on the community forum.
  • The more information you provide about what you did, what you tried, how your environment look like, the easiest it will be for people to help you.