Passbolt on Debian 8 “jessie” from scratch

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

Remy
Remy
Feb 27, 2017 · 12 min read

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

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

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 -pcreate database passbolt;exit;

Webserver installation (apache2)

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

apt-get install php5or the full listapt-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

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

mkdir /etc/apache2/sslopenssl 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

a2enmod ssla2enmod headersa2ensite default-ssl

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

ls -la /etc/apache2/sites-enabled

Pretty urls

a2enmod rewrite
fig. enabling mod_rewrite

Virtual host config

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

fig. quick and dirty domain name setting

Download passbolt

cd /var/wwwgit clone https://github.com/passbolt/passbolt_api.gitmv passbolt_api passbolt

Install php modules needed by passbolt

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.ininano /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

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/.gnupgchown 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

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

cd /var/www/passboltchown www-data:www-data app/Configchown -R root:www-data app/tmpchmod -R 770 app/tmpchmod -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

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

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

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?

passbolt

open source password manager for teams

Thanks to Cedric Alfonsi

Remy

Written by

Remy

homme à tout faire

passbolt

passbolt

open source password manager for teams

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade