Update Passbolt from source
Introduction
This tutorial is distribution agnostic. It details the installation steps at a high level, without taking into account the specifics related to each and every linux distribution. It is provided for reference only, to demonstrate that it is possible to install passbolt from source.
This is NOT the recommended way to update passbolt. You will find guides to install passbolt on your distribution here. You should most likely not attempt this unless you are an advanced administrator with very specific needs in terms of server configuration.
System requirements
Passbolt is reported to work on a large variety of operating system configurations. Therefore this help page is a generic guide that should work for most environments.
If you run into any issues with your particular configuration, please check the forum. Maybe someone else has had your issue. If not, make a post and the community will try to help you.
- Any Unix-like major distribution (Debian, Centos, Ubuntu, *BSD)
- A webserver (Apache or Nginx)
- A TLS server certificate for HTTPS
- PHP >= 7.4.0
PHP 8.1.0 will be required in the next major release
The following PHP extensions (that may or may not come by default):
- PHP-GNUPG: for key verification and authentication.
- CakePHP default requirements: Intl, mbstring, simplexml
- FastCGI Process Manager (FPM)
- Image manipulation: gd or imagick
- Database: Mysqlnd, pdo, pdo_mysql
- Some general default: xsl, phar, posix, xml, zlib, ctype, curl, json.
- Ldap
- & more depending on your configuration (for example if you want to use memcache for sessions).
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 httpd. 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 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 is present on your system
By default you should have git installed:
$ which git
/usr/bin/git
If not install the relative distribution package.
Check if composer is present on your system 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.
Passbolt requires composer v2, check the version you have already installed:
composer.phar --version
> Composer version 2.0.9 2021-01-27 16:09:27
To get the latest version of composer, you can check the composer installation instructions.
Updating 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. 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.
2. Get the latest code version
You can 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
3. 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
4. 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.
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:
sudo -H -u www-data bash -c "./bin/cake cache clear_all"
6. Bring your site back online
Almost done:
sudo systemctl start nginx
You can also run the following command:
sudo -H -u www-data bash -c "/usr/share/php/passbolt/bin/cake passbolt healthcheck"
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.