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.

For system specific step by step guide, you can refer to the following documentation:

• Debian 9 “Stretch” step by step guide
• CentOS 7 step by step guide
• Ubuntu 16.04.4 LTS (coming soon)

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).

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

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 'SERVER_KEY@EMAIL.TEST'

Copy the public and private keys to the passbolt config location:

$ gpg --armor --export-secret-keys SERVER_KEY@EMAIL.TEST > /var/www/passbolt_api/config/gpg/serverkey_private.asc
$ gpg --armor --export SERVER_KEY@EMAIL.TEST > /var/www/passbolt_api/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 <no-reply@passbolt.com>

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_api$ composer install

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

You can add a cron call to the script so the emails will be sent every minute. Add the following line to you crontab:

 * * * * * /var/www/passbolt_api/bin/cake EmailQueue.sender >> /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?

Feel free to ask for help on the community forum.