Passbolt on Debian 8 “jessie” from scratch

A step by step installation guide with php5, mariadb and apache

Having some issues when installing passbolt? You can always request some help on the community forum!

Update: passbolt v2 is out. This article was for the v1 and is now obsolete. Check out the online documentation for v2 guidelines and tutorials.

So you tried following the instructions in the official passbolt installation guide help page, but you feel some details are missing? Indeed, the instructions are generic and designed to be applicable to most *nix environments.

Let’s see in practice what it means to install passbolt step by step on a Debian stable environment (Debian 8.71 and passbolt 1.4.3 when this article is written). The goal of this tutorial is not to create an hardened installation, but more to create a minimal barebone passbolt instance you can use to test the application locally, before you start building your production environment.

Similarly some of these steps could be grouped together or scripted, but the idea here is to help newcomers understand what they are doing and why, and not rush through the installation in a record time.

Debian installation

fig. first step: getting a debian machine up and running

First step would be to install the Debian operating system. We will not cover it, as they are plenty of resources available online to cover that part. In our case here on the screenshots we are creating a virtual machine from the debian netinst iso.

fig. the Debian install is complete, that was quick!

Base packages

No need to install any particular package such as the webserver (apache) during the setup. Let’s stick to the bare minimum for now, as we will do the rest manually.

Since we will need administrator privileges to perform most of the steps, you could either setup sudo for your default user, or log in the terminal as root. This is what we will do for the rest of this tutorial.

su -

We can install some basic utilities at this stage: Git, make, the linux kernel headers and a compiler, as will all be needed later on.

fig. installing some base line tools and libraries

apt-get install make git-core g++ linux-headers-amd64

Note: If you do not use the latest kernel version or you use a different architecture, you can find out which package to install using the following:

$ uname -r
3.16.0-4-amd64

Database installation

Once the installation is complete and you are logged in, open a terminal. We can start by installing the database server. We will use mariadb here, but you could also use mysql.

apt-get install mariadb-server

fig. mariab-db server install

fig. all your database belong to us

You will need to choose a root password and ideally create another database user to control who has access to the database properly. For the sake of simplicity we will just use root in this tutorial.

fig. creating passbolt database

You can then log in into your database server and create the passbolt database, using the following:

mysql -u root -p
create database passbolt;
exit;

Webserver installation (apache2)

Next we will want to install the apache webserver that will serve our php application.

fig. apache2 installation

apt-get install apache2

We can see if this worked by opening up the web browser and going to the url: http://localhost. By default apache stores the web pages in /var/www/html so we can see and edit the default html page in this directory if needed.

fig. this is not the webpage you are looking for

PHP installation

Now let’s install php. By default the command line interface (php5-cli) and the apache mod for php (libapache2-mod-php5) will be also installed as dependencies. We will need them later on.

apt-get install php5
or the full list
apt-get install php5 php5-cli php5-common libapache2-mod-php5 php5-json php5-readline libonig2 libqdbm14

fig. <?php $action = $_GET[‘Coffee’]; ?>

You will need to restart your apache server for the changes to take place.

service apache2 restart

fig. a simple php info file

It’s a good idea to create a phpinfo file at the root directory of your apache folder, if you want to see that php works at that stage. You can also use this page later on, if needed, to see which modules are enabled.

nano /var/www/html/index.php
<?php phpinfo(); ?>

fig. php5.6 up and running

To see if this one works, we can go to http://localhost/index.php.

Now that we have php and mariadb we need to allow these two to talk to each other via a driver, mysql native driver in our case.

apt-get install php5-mysqlnd

fig. php5-mysqlnd driver

SSL certificate creation

It is recommended to use https with passbolt (and, well, pretty much everything). To setup SSL we need a certificate. Here for the sake of brevity we will create a self-signed certificate. Of course you are free to use a proper free certificate and tidy up the server supported cypher suites.

We will generate private and public keys and store them with the apache2 configuration as follows:

mkdir /etc/apache2/ssl
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.crt

Make sure you fill in the details as requested, for example:

Country Name (2 letter code) [AU]:AQ
State or Province Name []:South Antartica
Locality Name (eg, city) []:Amundsen-Scott
Organization Name (eg, company) []:Penguins Unlimited
Organizational Unit Name []:Ministry of slides
Common Name []:passbolt.yourdomain.com
Email Address []:admin@yourdomain.com

The most important line is the Common Name (e.g. server FQDN or YOUR name). You need to enter the domain name associated with your server or, if you don’t have one, the server’s public IP address.

Double check the file permissions for apache.key and apache.crt, to make sure the files are readable by the www-data user (the linux user that runs apache on Debian) and not available to everyobody else. For example:

chown root:www-data apache.key
chmod 640 apache.key

Enabling SSL apache module and site

You will then need to enable the default-ssl site on your webserver.

a2enmod ssl
a2enmod headers
a2ensite default-ssl

You can check it is enabled by looking in /etc/apache2/sites-enabled.

ls -la /etc/apache2/sites-enabled

Pretty urls

Before changing the SSL configuration of this virtual host, we want to also enable mod_rewrite, to allow passbolt to use “pretty urls”.

a2enmod rewrite

fig. enabling mod_rewrite

Virtual host config

For these apache modules to apply to our site we need to edit our virtual host configuration file to add the rewrite and the SSL rules.

nano /etc/apache2/sites-enabled/default-ssl.conf

Fig. editing the virtual host

This is what a minimal configuration file looks like. Of course you will need to replace your administrator email address (ServerAdmin setting) and server name (ServerName setting).

<IfModule mod_ssl.c>
    <VirtualHost _default_:443>
        ServerAdmin webmaster@localhost
        ServerName passbolt.dev
        DocumentRoot /var/www/passbolt
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
        SSLEngine on
        SSLCertificateFile /etc/apache2/ssl/apache.crt
        SSLCertificateKeyFile /etc/apache2/ssl/apache.key
 
        <Directory /var/www/passbolt>
            Options FollowSymLinks
            AllowOverride All
            Require all granted
        </Directory>
    
        <FilesMatch “\.(php)$”>
            SSLOptions +StdEnvVars
        </FilesMatch>
        BrowserMatch “MSIE [2–6]” \
          nokeepalive ssl-unclean-shutdown \
          downgrade-1.0 force-response-1.0
        BrowserMatch “MSIE [17–9]” ssl-unclean-shutdown
    </VirtualHost>
</IfModule>
# vim: syntax=apache ts=4 sw=4 sts=4 sr noet

Domain name setup

For the sake of keeping this demonstration short we will use passbolt.dev as domain name (we added the IP to domain name mapping with a manual entry in the /etc/hosts file after a quick lookup on ifconfig).

fig. quick and dirty domain name setting

Download passbolt

In the virtual host configuration file we are pointing to /var/www/passbolt but obviously it does not exist yet! Let’s create it, by cloning passbolt official repository. This way we can pull new releases easily in the future.

cd /var/www
git clone https://github.com/passbolt/passbolt_api.git
mv passbolt_api passbolt

Install php modules needed by passbolt

We still need to install a few php modules before trying out passbolt. First let’s install the library that will help the application handle images such as profile pictures.

apt-get install php5-gd

fig. image library

By default gnupg is installed on Debian but applications can not directly talk to it. For this we need to install GPGME, a wrapper library which provides a C API to access some of the GnuPG functions, such as encrypt, decrypt, sign and verify.

apt-get install libgpgme11-dev

fig. installing GPGME

For PHP to talk to GnuPG we also need a PECL extension called php-gnupg. So first we need to install pear and then build the extension.

apt-get install php-pear php5-dev

fig. php5-dev is pretty heavy-handed with dependencies

pecl install gnupg

fig. building gnupg.so part I

fig. building gnupg.so part II

As you can see in the terminal we need to manually add the gnupg.so extension to the php.ini.

There are two php ini files, one for apache and one for the command line tools. Let’s make sure we edit both.

nano /etc/php5/cli/php.ini
nano /etc/php5/apache2/php.ini

Add the following in the section talking about extensions (or at the bottom of the files).

extension=gnupg.so

Let’s restart apache one last time to activate all these configuration changes.

service apache2 restart

GPG keys generation

We have the gpg libraries installed but we have no gpg keys yet. We need to generate them.

fig. gpg key generation

By default gnupg expects the keyring to be in /home/<username> but you can also change that. So to keep things simple, we stick to the default and create a directory for the www-data user to store its gnupg keyring.

mkdir -m 0700 /home/www-data /home/www-data/.gnupg
chown www-data:www-data -R /home/www-data

Now let’s create the gpg secret and public keys that our server will use.

fig. gpg key generation

gpg --gen-key

Note: if you do not run this command as www-data the result will be stored in /root/.gnupg. Thankfully passbolt does import the keys at runtime into the www-data keyring if it is not already present.

It’s a good idea to fill in the details properly and not press enter frantically. Make sure you have decent name and email for the key. This will come in handy to identify and verify it down the line.

Important: Currently php-gnupg does not support keys with a passphrase so you will need to leave that field empty.

fig. gpg key generation, fingerprint in highlight

Make sure you note down the key fingerprint. We will need this later on.

Note: Running gpg --gen-key on a virtual machine can a while because /dev/random does not have enough “randomness” aka entropy. You can speed up the gpg key creation with the rng-tools package to improve the entropy generation.

The next step is to export this key from the root user keychain to the filesystem so that passbolt can load it in the apache user keychain if needed. Here we are placing them in app/Config/gpg, but they could be placed wherever apache can grab them.

fig. exporting the server gpg keys

gpg --armor --export-secret-keys passbolt@passbolt.dev > /var/www/passbolt/app/Config/gpg/serverkey.private.asc
gpg --armor --export passbolt@passbolt.dev > /var/www/passbolt/app/Config/gpg/serverkey.asc

Again here you will want to make sure that the keys in app/Config/gpg are only readable by www-data:

chown root:www-data serverkey*
chmod 640 serverkey*

Passbolt configuration

Almost there! We need now to configure passbolt app and we’re done.

fig. creating the configuration files from the defaults

Let’s copy the default configuration files to create our own versions.

cd /var/www/passbolt/app/Config
cp core.php.default core.php
cp database.php.default database.php
cp app.php.default app.php
cp email.php.default email.php

We need to edit the security salt and cipherSeed (digit only) in core.php. Both values are currently not in used, but they may be used in the future, so it is a mandatory step. Choose random values by for example throwing a few dice.

nano core.php

fig. security salt and cipherseed edit

We also want to change the App.fullBaseUrl to our selected domain so that all the links are correctly formatted. This will be used for example to display the avatar images in the notification emails.

Make sure you put https and not http as the main protocol!

Configure::write('App.fullBaseUrl', 'https://passbolt.dev');

fig. setting up the fullBaseUrl

We also need to set the right database name and user credentials in database.php.

nano database.php

You need to fill in the details for your database server. Here mostly login (e.g. root or whatever user you have created previously), password and database (passbolt). No need to edit other items, see the diff bellow:

diff database.php.default database.php
73,75c73,75
< ‘login’ => ‘user’,
< ‘password’ => ‘password’,
< ‘database’ => ‘database_name’,
- -
> ‘login’ => ‘root’,
> ‘password’ => ‘root’,
> ‘database’ => ‘passbolt’,

We the application to use reuse our freshly created gpg keys, as the default ones are insecure. For this we set the fingerprint and location right in app.php. To accomplish this we set the fingerprint and location in app.php (in the GPG Configuration section). Also take a moment to check the other application settings. You may want to allow public registration of users for example.

nano app.php

fig. app.php setting up key fingerprint

// Server private key location and fingerprint
'fingerprint’ => '<your fingerprint>', 
'public’ => APP . 'Config' . DS . 'gpg' . DS . 'serverkey.asc',
'private’ => APP . 'Config' . DS . 'gpg' . DS . 'serverkey.private.asc'

Passbolt installation

Since we need the installation script to run as www-data and that this script will need to write in the configuration we will give write access (ideally temporarily) to this user in this directory. While we are at it let’s make both writable the tmp directory and the directory where our users will upload pictures.

cd /var/www/passbolt
chown www-data:www-data app/Config
chown -R root:www-data app/tmp
chmod -R 770 app/tmp
chmod -R 770 app/webroot/img/public

fig. setting up the permissions in the writable directory

Let’s now run the install script as the www-data user.

su -s /bin/bash -c "app/Console/cake install --no-admin" www-data

fig. success!

You can at that step decide if you want to send anonymous statistics about your passbolt usage. Cool kids do, because it helps the developers to make passbolt better for everyone.

Create the first user

At last, passbolt is up and running! But there is no user yer. So let’s create our first user, the administrator.

fig. creating the first admin user

app/Console/cake passbolt register_user -u admin@passbolt.dev -f ada -l lovelace -r admin

Follow the link in the terminal to start the setup process, in the browser, for this admin user. Once logged in, we can start creating passwords.

fig. emptyness

Emails

Before inviting other users we need to wrap-up the email configuration in app/Config/email.php.

fig. email configuration

We also need a cron job to send periodically the emails from the queue.

crontab -e

The following will send emails every minutes.

* * * * * /var/www/passbolt/app/Console/cake EmailQueue.sender > /var/www/passbolt/app/tmp/email.log

Debug mode & healthcheck

It is possible to get a healthcheck of the current installation by going to /healthcheck, either while being logged in as an administrator or by setting debug to true in core.php.

fig. healthcheck

Do let us know if you run into problems following this tutorial on the support forum. You can also check our help section directly on our website.

Thank you for trying out passbolt!

—

If you like passbolt you should consider giving some love back. No need to be a developer: every little help count. For example you can write a review on chrome web store or firefox addon marketplace, or give a star on github. Do you want to know more?