Update passbolt server component (v2)
Which update process to follow?
Each passbolt release follows the concept of Semantic Versioning. Given a version number MAJOR.MINOR.PATCH, we increment as follow:
- PATCH version when we make backwards-compatible bug fixes. So let’s say you are running passbolt v2.0.2 and the latest one available is v2.0.3 you will need to perform a patch update.
- MINOR version when we add functionality in a backwards-compatible manner. Similarly say you have passbolt v2.0.3 installed and the latest version available is v2.1.0, you will need to perform a minor version update.
- MAJOR version when incompatible API changes are made. You get the deal for major version update: that would mean going from v1 to v2 for example.
Where to find the latest release version number?
You can find information about which version is the latest in the release notes. It is generally a good idea to check these notes before running an update. You can also find it on the official GIT repository.
Where to find the version number for a given installation?
You can check
app/Config/version.php to know the version number for your local instance. You can also hover on the heart icon at the bottom right corner of any passbolt screen. The first item is the server version, the second the one from the browser extension.
Please see the following documentation to Update from v1 to v2
Every now and again some releases will introduce some database and/or configuration files changes. Here is a step by step guide on how to perform a minor update. Just replace the version numbers where necessary.
1. Take your site down
Create a temporary webserver configuration to redirect all the requests to a maintenance page. You can find resources how to do this online: here is an example for apache .
2. Get the latest release
You can also pull the latest version directly from master:
$ git pull origin master
You can also pull specific versions:
$ git fetch $ git checkout tags/v2.3.0
3. Update the libraries
Some libraries are not packaged with the software but need to be updated using composer, based on what is recommended in the composer.lock. This file is provided by passbolt.
$ composer install --no-dev
4. Run the migration script
You can run the database migration scripts as follow:
$ ./bin/cake passbolt migrate --backup
As you can see with the command above you can optional ask the application to create a database backup. This is usefull in case you run into any issues with the new version and need to revert to an old but working one.
This backup will be placed in
5. 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:
$ ./bin/cake cache clear_all
6. Put your site back online!
As an administrator (or as any user in debug mode) you can go and check on the /healthcheck page to see if your instance configuration is looking good.
Performing a patch update is the easiest. All you need to do is checkout the latest version.
$ git pull origin master
You can also checkout a specific version and use branches to switch versions. For example for version 2.0.3:
$ git fetch --tags $ git checkout tags/v2.3.0 -b tags/v2.3.0
Verifying the status of the application
Optionally, you can login as an administrator and check the status on the healthcheck page:
You can also run the following command:
./bin/cake passbolt healthcheck
If you run into some issues
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
- 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, mysql 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.
This article was last updated on May 2nd, 2018.