fig. passbolt welcome page before configuration
For this tutorial, you will need:
A minimal server.
The recommended server requirements are:
FAQ pages:
For easier installation and update tasks Passbolt provides a package repository that you need to setup before you download Passbolt and install it.
Step 1. Download our dependencies installation script:
wget "https://download.passbolt.com//installer/passbolt-repo-setup..sh"
Step 2. Download our SHA512SUM for the installation script:
wget https://github.com/passbolt/passbolt-dep-scripts/releases/latest/download/passbolt--SHA512SUM.txt
Step 3. Ensure that the script is valid and execute it:
sha512sum -c passbolt--SHA512SUM.txt && sudo bash ./passbolt-repo-setup..sh || echo \"Bad checksum. Aborting\" && rm -f passbolt-repo-setup..sh
sudo install passbolt--server
Before you can use the application, you need to configure it. Point your browser to the hostname / ip where passbolt can be reached. You will reach a getting started page.
fig. passbolt welcome page before configuration
The first page of the wizard will tell you if your environment is ready for passbolt. Solve issues if any and click on “Start configuration” when ready.
fig. wizard - healthcheck
This step is about telling passbolt which database to use. Enter the host name, port number, database name, username and password.
fig. wizard - database
In this section you can either generate or import a GPG key pair. This key pair will be used by passbolt API to authenticate itself during the login handshake process.
Generate a key if you don’t have one.
fig. wizard - generate a key pair
Optional: Import a key if you already have one and you want your server to use it.
To create a new GnuPG key without passphrase:
gpg --batch --no-tty --gen-key <<EOF
Key-Type: default
Key-Length: 2048
Subkey-Type: default
Subkey-Length: 2048
Name-Real: John Doe
Name-Email: email@domain.tld
Expire-Date: 0
%no-protection
%commit
EOF
Feel free to replace Name-Real and Name-Email with your own.
To display your new key:
gpg --armor --export-secret-keys email@domain.tld
fig. wizard - import a key pair
At this stage, the wizard will ask you to enter the details of your SMTP server.
fig. wizard - smtp mail server details
You can also test that your configuration is correct by using the test email feature at the right of your screen. Enter the email address at which you want the wizard to send you a test email and click on “Send test email”.
fig. wizard - test smtp settings
The wizard will then ask you what preferences you prefer for your instance of passbolt. The recommended defaults are already pre-populated but you can also change them if you know what you are doing.
fig. wizard - preferences
You need to create the first admin user account. This first admin user is probably you, so enter your details and click on next.
fig. wizard - first user
That’s it. The wizard has now enough information to proceed with the configuration of passbolt. Sit back and relax for a few seconds while the configuration process is going on.
fig. wizard - installation
Your user account is now created. You will see a redirection page for a few second and then will be redirected to the user setup process so that you can configure your user account.
fig. wizard - completion and redirection
Before continuing passbolt will require you to download its plugin. If you already have it installed you can go to the next step.
fig. download the browser extension
Passbolt will ask you to create or import a key that will be later use to identify you and encrypt your passwords. Your key needs to be protected by a password. Choose it wisely, it will be the gatekeeper to all your other passwords.
fig. generate a key
This step is essential. Your key is the only way to access your account and passwords.
fig. download the recovery kit
Choosing a color and a three characters token is a secondary security mechanism that helps you to mitigate phishing attacks. Each time you are performing a sensitive operation on passbolt, you should see this token.
fig. define your security token
Your administrator account is configured. You will be redirected to the login page of passbolt. Enjoy!
For this tutorial, you will need:
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.
First things first, as this is a sensitive operation a backup of the instance must be performed to prevent any data loss. You can follow our backup process.
Pull the latest version directly from master:
$ cd /var/www/passbolt
$ sudo -H -u nginx bash -c "git pull origin master"
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.
Passbolt requires composer v2, check the version you have already installed:
$ sudo -H -u nginx bash -c "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.
Update the dependencies:
$ sudo -H -u nginx bash -c "php -d allow_url_fopen=on composer.phar install --no-dev -n -o"
A new version can come with a data structure change. You can run the migration scripts as follow:
$ sudo -H -u nginx bash -c "./bin/cake passbolt migrate"
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 nginx bash -c "./bin/cake cache clear_all"
Almost done:
$ sudo systemctl start nginx
Optionally, you can login as an administrator and check the status on the healthcheck page:
fig. Example of healthcheck screen
You can also run the following command:
$ sudo -H -u bash -c "/usr/share/php/passbolt/bin/cake passbolt healthcheck"
If you run into some issues:
logs directoryWhere to get help:
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 October 19th, 2021.