Help Search

Update passbolt server component (v2)

Pre-requisites

Find out where is your passbolt directory

All the commands hereafter should be done from inside your passbolt directory:

$ cd /var/www/passbolt

By default passbolt should be installed under /var/www/passbolt but it could be different if you installed from source manually. We will assume for the rest of this tutorial that it is located in /var/www/passbolt.

Find out the name of your webserver user

Some commands need to be run as the same user running the web server. Generally on Debian systems it will be www-data but on other distributions like Centos it could be for example nginx or http. For the rest of this tutorial we will assume that the user named www-data.

Generally it is not possible to login as this user, so in order to run the command as this user, you can execute something like this:

$ sudo -H -u www-data bash -c "./bin/cake passbolt healthcheck"

This command for example, will run the healthcheck command as www-data data user. It is a good idea to start with running a healthcheck prior to updating, to make sure everything is in order.

Make sure the permissions are right for your current user

Do not run the commands as root when updating passbolt. It can render your installation unusable.

Running commands as root can make your installation unusable until the permissions are repaired. We recommend you use another user for this purpose. The whoami command will let you know which user you are logged in as. In our case below, it is the user passbolt.

$ whoami
passbolt

You need to make sure that this user have access to the passbolt directory. The easiest way to do this would be to add such user to the www-data and sudo groups, so for example for a passbolt user, you could execute as root:

$ sudo usermod -a -G www-data passbolt
$ sudo usermod -a -G sudo passbolt

You can check if the user is included in the group (you may need to logout / login again for the permissions to be applied):

$ groups passbolt
passbolt : passbolt www-data sudo

Make sure the passbolt directory is owned by the passbolt user and accessible to the www-data group. You can set the permissions as follow:

$ sudo chown -R passbolt:www-data .
$ sudo chmod -R o-rwx .
$ sudo find . -type d -print0 | xargs -0 sudo chmod g-w
$ sudo find . -type f -print0 | xargs -0 sudo chmod g-wx
$ sudo chmod g+x ./bin/cake
$ sudo find ./tmp -type d -print0 | xargs -0 sudo chmod 770
$ sudo find ./tmp -type f -print0 | xargs -0 sudo chmod 660
$ sudo find ./logs -type d -print0 | xargs -0 sudo chmod 770
$ sudo find ./logs -type f -print0 | xargs -0 sudo chmod 660
$ sudo find ./webroot/img/public -type d -print0 | xargs -0 sudo chmod 770
$ sudo find ./webroot/img/public -type f -print0 | xargs -0 sudo chmod 660

Check that the permissions are set as expected.

$ ls -la .
drwxr-x--- 2 passbolt www-data  .
drwx------ 6 root root          ..
drwxr-x--- 6 passbolt www-data  config

Make sure the passbolt directory doesn’t contain any changes. If you have altered the passbolt code, stash your changes before executing the following command.

$ git checkout HEAD .

Check if git and composer are present on your system

By default you should have both composer and git installed:

$ which git
/usr/bin/git

You should also already have composer installed.

$ which composer.phar
/usr/bin/composer.phar

Depending on your setup it is possible that your composer command is named composer and not composer.phar.

If for some reason the command above fails because you don’t have composer installed, you can check the composer installation instructions.

Updating passbolt

0. 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. For example if you are using nginx as a webserver:

$ sudo systemctl stop nginx

If you feel a bit more fancy, you can change your web server configuration to point to an “under maintenance” page. It is a good practice to announce such maintenance window to your users in advance, so that they can also plan for the update, for example by downloading some key passwords they may need.

1. Get the latest code version

You can also pull the latest version directly from master:

$ git pull origin master

To pull a specific version you can do:

$ git fetch origin tags/v2.13.0
$ git checkout tags/v2.13.0

On installations based on install scripts or in the VM appliance you are in a shallow clone state so to change the branch you will need to:

$ git remote set-branches origin "*"
$ git fetch origin tags/v2.13.0
$ git checkout tags/v2.13.0

2. update the dependencies

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.

$ php -d allow_url_fopen=on /usr/bin/composer.phar install --no-dev -n -o

3. Run the migration script

You can run the database migration scripts as follow:

$ sudo -H -u www-data bash -c "./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 useful 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.

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 "./bin/cake cache clear_all"

5. Take your site back up

Almost done:

sudo systemctl start nginx

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:

$ sudo -H -u www-data bash -c "./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 June 25th, 2020.

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!

🍪   Do you accept cookies for statistical purposes? (Read more) Accept No thanks!