Help Search

Upgrade Passbolt CE from v1 to v2

This tutorial covers the case where you want to upgrade your current instance of passbolt CE v1.x into passbolt CE v2.x.

Important: Please take a full backup of your passbolt before proceeding with the upgrade. Backup should include passbolt files as well as the database.

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.0.0
  • Mysql >= 5.5.59
  • Composer
  • GnuPG
  • Git

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
  • Image manipulation: gd or imagick
  • Database: Mysqlnd, pdo, pdo_mysql
  • Some general default: xsl, phar, posix, xml, zlib, ctype, curl, json.
  • & more depending on your configuration (for example if you want to use memcache for sessions).

Upgrade with a new server

Considering that the system requirements haved it may make sense for you to upgrade on a fresh server. If that is what you want to do, copy the v1 backup files to your new server, import your passbolt database into your new server and proceed like you were upgrading on the same server, with the process described bellow.

Upgrade from the same server

In the following examples we assume you are running passbolt v1 using apache in the /var/www/passbolt directory. You will need to replace these values with your local environment settings.

1. Make sure you have the latest v1.x version

If you do not have the latest version, please follow the regular v1 udpate process. We’ll also assume you have a web server that match the system requirements.

/var/www/passbolt$ cat app/Config/version.php  | grep number
'number' => '1.6.10'

2. Take your site offline

There are multiple ways of doing that, the simplest is sending a notice by email to your users and stopping your webserver. The better approach would be to create a temporary html file and redirect your passbolt user there, for example:

/var/www$ mkdir wip
/var/www$ touch wip/index.html
/var/www$ echo '<html><head><title>Maintenance in progress</title></head><body><h1>Maintenance in progress</h1></body></html>' >> wip/index.html
/var/www$ nano /etc/apache2/sites-enabled/001-default.conf

<IfModule mod_ssl.c>
        <VirtualHost _default_:443>
                ServerAdmin webmaster@localhost
                ServerName www.passbolt.test
                DocumentRoot /var/www/wip

                ErrorLog ${APACHE_LOG_DIR}/error.log
                CustomLog ${APACHE_LOG_DIR}/access.log combined

                SSLEngine on
                SSLCertificateFile /etc/apache2/ssl/passbolt.crt
                SSLCertificateKeyFile /etc/apache2/ssl/passbolt.key

        <Directory /var/www/wip>
            Options FollowSymLinks
            AllowOverride All
            Require all granted
        </Directory>

        </VirtualHost>
</IfModule>
/var/www$ service apache2 restart

3. Download the v2

Open a shell with the same user as your web server user. (usually, www-data for apache, nginx for nginx)

/var/www$ su -s /bin/bash www-data

Replace the previous passbolt by the new version.

/var/www$ mv ./passbolt ./passbolt_old
/var/www$ git clone https://github.com/passbolt/passbolt_api.git ./passbolt

4. Install the dependencies

/var/www$ cd ./passbolt
/var/www/passbolt$ composer install

5. Copy the avatar folder

/var/www/passbolt$ cp -R ../passbolt_old/app/webroot/img/public/* ./webroot/img/public/.
/var/www/passbolt$ mv ./webroot/img/public/images/ProfileAvatar ./webroot/img/public/images/Avatar

6. Copy the server gpg key

/var/www/passbolt$ cp ../passbolt_old/app/Config/gpg/* config/gpg/.

7. Create a passbolt configuration file

The name and values in the main configuration file have changed. Everything is now located in one file called config/passbolt.php. Do not copy your v1 configuration files, instead you need to create a new one:

/var/www/passbolt$ cp config/passbolt.default.php config/passbolt.php
/var/www/passbolt$ nano config/passbolt.php

Even if the format has changed the information needed are pretty much the same than v1. You will need to set at least the following:

  • Application full base url
  • Database configuration
  • Email settings
  • Server OpenPGP key fingerprint.

You can also set your configuration using environment variables. Check config/default.php to get the names of the environment variables.

8. Run the migration script

The structure of the database changed in version 2. Make sure you run the following script to migrate your data to the new format.

/var/www/passbolt$ ./bin/cake passbolt migrate

Optionally you can also run the health check to see if everything is fine.

$ sudo su -s /bin/bash -c "./bin/cake passbolt healthcheck" www-data

9. Get your service back online

Edit your apache or nginx to point to the new directory and bring your service back online.

$ nano /etc/apache2/sites-enabled/001-default.conf
$ service apache2 restart

Last updated

This article was last updated on March 14th, 2018.

Are you experiencing issues when installing passbolt?

Ask the community!

Available on docker hub

Docker Logo

Get passbolt container!

Something is not accurate in this documentation? You can contribute by opening an issue or making pull requests!

View on github

We highly recommend that you install https on your server. You can get a free SSL certificate with the let's encrypt initiative.

let's encrypt!