Install passbolt API 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.
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
- MariaDB/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.
- Ldap
- & more depending on your configuration (for example if you want to use memcache for sessions).
Installation steps
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.
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:
$ gpg --armor --export-secret-keys [email protected] > /var/www/passbolt/config/gpg/serverkey_private.asc
$ gpg --armor --export [email protected] > /var/www/passbolt/config/gpg/serverkey.asc
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
is called 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
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.
Check 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/cake EmailQueue.sender >> /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!
Troubleshooting
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?
Feel free to ask for help on the community forum.
Last updated
This article was last updated on November 13th, 2018.