Install passbolt API from source
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.
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.3.0
- MariaDB/Mysql >= 5.5.59
- Composer >= 2
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).
1. Create a web server matching the system requirements.
Spin up a new fresh server with your favorite distribution, install a database server and a webserver with a TLS certificate. If you are using apache as web server make sure you have mod_rewrite module enabled.
Find out your web server 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
For the rest of this tutorial we will assume that the user named
2. Create an empty database
Connect to your mysql server and create new database. Make sure it is in the utf8mb4 char set to support non latin characters and emojis. 👏
/var/www$ mysql -u[user] -p[password] mysql> CREATE DATABASE passbolt CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; mysql> exit;
3. Clone the repository
Cloning the code using git will allow you to keep the source under version control and facilitate subsequent updates.
/var/www$ git clone https://github.com/passbolt/passbolt_api.git /var/www$ mv passbolt_api passbolt
4. Generate an OpenPGP key
Passbolt API uses an OpenPGP key for the server in order to authenticate and sign the outgoing JSON requests. For improved compatibility we recommend that you use the same GnuPG version for generating the keys and for the php module.
$ gpg --gen-key
After creating the key make sure you note down the fingerprint, it will be requested later in the install process. You can get the server key fingerprint as follow:
$ gpg --list-keys --fingerprint | grep -i -B 2 '[email protected]'
Copy the public and private keys to the passbolt config location:
5. Initialize the gpg keyring
In order for passbolt authentication to work your server key needs to be in the keyring used by the web server. It is likely that there is none, so you can create one by interacting with gpg with the web server user
The webserver name depends on your distribution and web server technology of choice, for example Apache user
www-data on Debian:
$ sudo su -s /bin/bash -c "gpg --list-keys" www-data pub 4096R/573EE67E 2015-10-26 [expires: 2019-10-26] Key fingerprint = 2FC8 9458 33C5 1946 E937 F9FE D47B 0811 573E E67E uid Passbolt Server Test Key <[email protected]>
6. Install the dependencies
The project dependencies such as the plugin to manage the images, emails, etc. are not included anymore in the code on the official repository. Fret not, composer will manage this for us.
/var/www/passbolt$ composer install --no-dev
Depending on your setup it is possible that your composer command is named
composer and not
If for some reason the command above fails because you don’t have composer installed, you can check the composer installation instructions.
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:
$ cp config/passbolt.default.php config/passbolt.php $ 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.
config/default.php to get the names of the environment variables.
8. Run the install script
Make sure you run the installation script as the web server user:
$ sudo su -s /bin/bash -c "./bin/cake passbolt install" www-data
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. Setup the emails
For passbolt to be able to send emails, you must first configure properly the “EmailTransport” section in the
config/passbolt.php file to match your provider smtp details.
Emails are placed in a queue that needs to be processed by the following shell.
$ ./bin/cake EmailQueue.sender
In order to have your emails sent automatically, you can add a cron call to the script so the emails will be sent every minute. Run the following command to edit the crontab for the www-data user:
$ crontab -u www-data -e
Add the following line to the crontab:
You can add a cron call to the script so the emails will be sent every minute. Add the following line to you crontab: ```bash * * * * * /var/www/passbolt/bin/cron >> /var/log/passbolt.log
If the log file does not yet exist, you can create it with the following command:
$ touch /var/log/passbolt.log && chown www-data:www-data /var/log/passbolt.log
And you are done!
Here are some frequently asked questions related to passbolt installation:
- Why do I see an unsafe mode banner in the footer?
- Why are my emails not being sent?
- Why should I install haveged on virtual environments?
- Why am I getting ldap synchronization issues?
Feel free to ask for help on the community forum.
This article was last updated on November 13th, 2018.