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.3.0
• MariaDB/Mysql >= 5.5.59
• Composer >= 2
• 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
• FastCGI Process Manager (FPM)
• 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.

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 nginx or http. For the rest of this tutorial we will assume that the user named www-data.

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.

WARNING: Some of the following commands such as the GnuPG parts need to be run as www-data. In order to do that, we recommend using

$ sudo su -s /bin/bash -c "run the command here" www-data

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 protected]
  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 protected]

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

You no longer need to be connected as www-data from now. In order for passbolt authentication to work your server key needs to be in the keyring used by the web server.

$ 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 composer.phar.

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.

WARNING: The OpenPGP key fingerprint has to be written with no spaces

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. Configure Nginx

Configure Nginx for serving HTTPS

Depending on your needs there are two different options to setup nginx and SSL :

• Auto (Using Let’s Encrypt)
• Manual (Using user-provided SSL certificates)

Be sure to write down the full path to your cert/key combo, it will be needed later in the Nginx configuration process.

Please, notice that for security matters we highly recommend to setup SSL to serve passbolt.

Configure Nginx to serve passbolt

For Nginx to serve passbolt, you will need to set up a server block file :

$ nano /etc/nginx/sites-enabled/passbolt.conf

You can use this default configuration sample (do not forget to replace PLACEHOLDERS with your values):

• SERVER_NAME with your localhost/virtualhost address
• CERTIFICATE_PATH with the path where cert.pem is located
• KEY_PATH with the path where key.pem is located
• PHP_VERSION with the PHP version you are using

server {
  listen [::]:443 ssl http2;
  listen 443 ssl http2;

  server_name SERVER_NAME;

  client_body_buffer_size     100K;
  client_header_buffer_size   1k;
  client_max_body_size        5M;
  client_body_timeout   10;
  client_header_timeout 10;
  keepalive_timeout     5 5;
  send_timeout          10;

  ssl_certificate     CERTIFICATE_PATH;
  ssl_certificate_key KEY_PATH;
  ssl_session_timeout 1d;
  ssl_session_cache shared:MozSSL:10m;  # about 40000 sessions
  ssl_session_tickets off;
  ssl_protocols TLSv1.2 TLSv1.3;
  ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
  ssl_prefer_server_ciphers off;
  root /var/www/passbolt/webroot;
  index index.php;
  location / {
    try_files $uri $uri/ /index.php?$args;
  }
  location ~ \.php$ {
    try_files                $uri =404;
    include                  fastcgi_params;
    fastcgi_pass             unix:/run/php/PHP_VERSION-fpm.sock;
    fastcgi_index            index.php;
    fastcgi_intercept_errors on;
    fastcgi_split_path_info  ^(.+\.php)(.+)$;
    fastcgi_param            SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param            SERVER_NAME $http_host;
    fastcgi_param PHP_VALUE  "upload_max_filesize=5M \n post_max_size=5M";
  }
}

Then, reload the Nginx process so that it takes your new configuration into account :

$ sudo systemctl reload nginx

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

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/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!

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?
• Why am I getting ldap synchronization issues?

Feel free to ask for help on the community forum.