Help Search

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.

footer version helper fig. footer version helper

Major update

Please see the following documentation to Update from v1 to v2

Minor update

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 ./tmp/cache/database/backup/backup_timestamp.sql.

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.

Patch update

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

Troubleshooting

Verifying the status of the application

Optionally, you can login as an administrator and check the status on the healthcheck page:

Example of healthcheck screen fig. Example of healthcheck screen

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 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, 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.

Last updated

This article was last updated on May 2nd, 2018.

Are you still using passbolt v1? Check out the previous version of this article.

See previous version

Are you experiencing issues when updating passbolt?

Ask the community!