Help Search

Install passbolt from scratch on CentOS 7

System requirements

Spin up a new fresh server with CentOS 7. Make sure that it is up-to-date.

Installation steps

1. Base packages

No need to install any particular package such as the webserver (nginx) during the initial 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.

sudo bash

Let’s first update our yum database and enable EPEL repositories to install all the required passbolt components:

$ yum update
$ yum -y install yum-utils epel-release

We also install remi’s repositories which will be helpful for PHP 7.2

$ yum -y install 'http://rpms.remirepo.net/enterprise/remi-release-7.rpm'
$ yum-config-manager --enable 'remi-php72'

Finally, we can install some basic utilities:

  • gcc is required to build php-gnupg extension throuhg PECL.
  • git will be required to clone passbolt source code
  • policycoreutils-python will install some binaries to easily manage selinux policies such as semanage.
$ yum -y install unzip wget composer policycoreutils-python git gcc 

2. Database installation

Then, we can install the database server. We will use mariadb here, but you could also use mysql.

$ yum install mariadb-server -y

Let’s make sure that the database is started

$ systemctl start mariadb

By default, MariaDB / MySQL is installed with basic security, and no root password. Let’s fix this.

$ mysql_secure_installation

Answer the questions and set a strong root password for the db.

Let’s now create a specific passbolt user and database.

$ mysql -u root -p
mysql > create database passbolt;
mysql > create user passbolt;
mysql > grant all on passbolt.* to 'passbolt'@'localhost' identified by 'strong_db_password';
mysql > flush privileges;
mysql > quit;

3. Webserver installation (Nginx)

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

$ yum install nginx -y
$ systemctl start nginx

We can see if this worked by opening up the web browser and going to the url: http://localhost (or whatever hostname / ip used by your machine). By default nginx stores the web pages in /usr/share/nginx/html/ so we can see and edit the default html page in this directory if needed.

4. PHP installation

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

$ yum -y install php-intl php-gd php-mysql php-mcrypt php-pear php-devel php-mbstring php-fpm gpgme-devel

Install php-fpm

$ yum install -y php-fpm
$ systemctl enable php-fpm
$ systemctl start php-fpm

We will be making use of the default nginx user to run both nginx and php-fpm. FPM out of the box uses the apache user but it is easy to change:

Edit /etc/php-fpm.d/www.conf with your preferred editor and modify the user/group configuration parameter to ‘nginx’:

$ vi /etc/php-fpm.d/www.conf
user = nginx
group = nginx

We also need to change the default group owner of the default php session directory so that it belongs to nginx.

chgrp nginx /var/lib/php/session

Passbolt needs GnuPG and it corresponding php module to run

$ pecl install gnupg
$ echo "extension=gnupg.so" > /etc/php.d/gnupg.ini

You will need to restart your nginx server, and php-fpm for the changes to take place.

$ systemctl restart nginx
$ systemctl restart php-fpm

5. Web server configuration

For nginx to work with passbolt we need to edit its configuration file to point to the passbolt folder (which will be created later) and rewrite rules. We also consider that passbolt will be reachable on the hostname passbolt.dev.

For now, we will configure it without SSL for the sake of keeping it simple.

$ vi /etc/nginx/conf.d/default.conf

Below is an example of configuration you can use in /etc/nginx/conf.d/default.conf

server {
  listen 80;
  server_name passbolt.dev;
  client_body_buffer_size     100K;
  client_header_buffer_size   1k;
  client_max_body_size        100k;
  client_body_timeout   10;
  client_header_timeout 10;
  keepalive_timeout     5 5;
  send_timeout          10;
  root /var/www/passbolt/webroot;

  location / {
    try_files $uri $uri/ /index.php?$args;
    index index.php;
  }
  
  location ~ \.php$ {
    fastcgi_index           index.php;
    fastcgi_pass            127.0.0.1:9000;
    fastcgi_split_path_info ^(.+\.php)(.+)$;
    include                 fastcgi_params;
    fastcgi_param           SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param           SERVER_NAME $http_host;
  }
  
  location ~* \.(jpe?g|woff|woff2|ttf|gif|png|bmp|ico|css|js|json|pdf|zip|htm|html|docx?|xlsx?|pptx?|txt|wav|swf|svg|avi|mp\d)$ {
    access_log off;
    log_not_found off;
    try_files $uri /webroot/$uri /index.php?$args;
  }
}

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

$ vi /etc/hosts

Add this line to the file

127.0.0.1 passbolt.dev

Of course, replace 127.0.0.1 by whichever ip is used by your host.

7. Download passbolt source code

In the web server 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 ./passbolt

8. Generate an OpenPGP key

Passbolt API uses an OpenPGP key for the server in order to authenticate and sign the outgoing JSON requests.

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

# Only in case of container or VM
$ yum install haveged -y
$ systemctl start haveged

Now generate an OpenPGP key

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

$ gpg --gen-key

Note: if you do not run this command as nginx the result will be stored in /root/.gnupg. Thankfully passbolt does import the keys at runtime into the nginx 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.

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 follows:

$ gpg --list-keys --fingerprint | grep -i -B 2 'SERVER_KEY@EMAIL.TEST'
pub   2048R/28EEB539 2018-04-18
      Key fingerprint = 480E 9564 0F27 6562 39D6  7BF5 8AB6 8641 28EE B539
uid                  firstname lastname <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/config/gpg/serverkey_private.asc
$ gpg --armor --export SERVER_KEY@EMAIL.TEST > /var/www/passbolt/config/gpg/serverkey.asc

We don’t want those keys to be readable by anyone, except the webserver.

$ chmod 640 /var/www/passbolt/config/gpg/serverkey*

9. Initialize the webserver 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

In centos 7, the home directory of the web server user nginx is /var/lib/nginx.

We create the keyring for the webserver:

$ sudo su -s /bin/bash -c "gpg --list-keys" nginx
gpg: directory '/var/lib/nginx/.gnupg' created
gpg: keybox '/var/lib/nginx/.gnupg/pubring.kbx' created
gpg: /var/lib/nginx/.gnupg/trustdb.gpg: trustdb created

10. Set passbolt file permissions

We need to set the right permissions on the passbolt files. It should belong to the same owner as the webserver.

$ chown -R  nginx:nginx /var/www/passbolt
$ cd /var/www/passbolt

Important: For the following steps, we’ll also need to use the same user as the one running the webserver. In our case (nginx), it is nginx.

$ su -s /bin/bash nginx

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

$ composer install

12. Create a passbolt configuration file

Everything is located in one configuration file called config/passbolt.php.

$ cp config/passbolt.default.php config/passbolt.php
$ vi config/passbolt.php

You will need to set at least the following:

  • Application full base url
  • Database configuration
  • Server OpenPGP key fingerprint (you noted it down before)

Ignore the email configuration for now. We will take care of it later.

For now, we will also deactivate the force_ssl parameter for the sake of having a functional passbolt quickly. We’ll activate ssl later.

The sections of your configuration file should look similar to this:

[
    'App' => [
        'fullBaseUrl' => 'http://passbolt.dev',
    ],

    // Database configuration.
    'Datasources' => [
        'default' => [
            'host' => 'localhost',
            'username' => 'passbolt',
            'password' => 'your_password',
            'database' => 'passbolt',
        ],
    ],
    'passbolt' => [
        'ssl' => [
            'force' => false,
        ],
        'gpg' => [ 
            // Main server key.
            'serverKey' => [
                // Server private key fingerprint.
                'fingerprint' => '1C765F5273EC9AF56300BC6F6C76DA6B9F23C8BB',
                //'public' => CONFIG . 'gpg' . DS . 'serverkey.asc',
                //'private' => CONFIG . 'gpg' . DS . 'serverkey_private.asc',
            ],
        ],
    ],
]

For now, do not forget to add ssl.force => false as seen above, or passbolt will redirect all your connections to a https socket, which will not work since it is not yet configured.

'ssl' => [
    'force' => false,
],

You can also set your configuration using environment variables. Check config/default.php to get the names of the environment variables.

13. Run the install script

Let’s install passbolt tables and data in the database.

$ ./bin/cake passbolt install

The install script will ask you to create an admin user. Enter your first name, last name and email. In return, the script will provide you with an activation link that you will user later to activate and configure your user. You can go to this url now or later, but we recommend that you configure SSL before.

Optionally you can also run the health check to see if everything is fine.

$ ./bin/cake passbolt healthcheck

You should see a majority of green ok. However, some SSL related alerts should still appear.

14. Set Selinux permissions

If your CentOS installation comes with SElinux enabled please follow this steps to make sure that passbolt works with it. If SElinux is disabled, there is no need to enable it in order for passbolt to work.

Check that selinux is enabled using (as root):

$ sestatus
SELinux status:                 enabled
SELinuxfs mount:                /sys/fs/selinux
SELinux root directory:         /etc/selinux
Loaded policy name:             targeted
Current mode:                   enforcing
Mode from config file:          enforcing
Policy MLS status:              enabled
Policy deny_unknown status:     allowed
Max kernel policy version:      28

First we grant access to the httpd service (nginx) access to the files under /var/www recursively so it will also have access to /var/www/passbolt files.

$ semanage fcontext -a -t httpd_sys_content_t '/var/www(/.*)?'

Passbolt will need to write on the tmp directory (for file caching for example) we grant read and write access to the httpd service to these directories:

$ semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/passbolt/tmp(/.*)?'

Passbolt will also need to write on the logs directory. We grant read and write access to the httpd service to these directories:

$ semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/passbolt/logs(/.*)?'

Once the permissions are in place we tell SELinux to upgrade the file tags that we have just changed:

$ restorecon -Rv /var/www

Passbolt and therefore the httpd service require read and write access to nginx gnupg keyring:

$ semanage fcontext -a -t httpd_sys_rw_content_t '/var/lib/nginx/.gnupg(/.*)?'
$ restorecon -Rv /var/lib/nginx/.gnupg

For more information on SELinux: https://wiki.centos.org/HowTos/SELinux

15. It’s running

At this stage, passbolt is running as it should, but https is still missing. It is strongly recommended that you configure https before using passbolt. We will go through it in the next section, as well as the emails configuration.

Going further

1. Setup the emails

For passbolt to be able to send emails, you must first configure properly the “EmailTransport” and “Email” section in the config/passbolt.php file to match your provider smtp details.

// Email configuration.
    'EmailTransport' => [
        'default' => [
            'host' => 'localhost',
            'port' => 25,
            'username' => 'user',
            'password' => 'password',
            // Is this a secure connection? true if yes, null if no.
            'tls' => null,
            //'timeout' => 30,
            //'client' => null,
            //'url' => null,
        ],
    ],
    'Email' => [
        'default' => [
            // Defines the default name and email of the sender of the emails.
            'from' => ['passbolt@your_organization.com' => 'Passbolt'],
            //'charset' => 'utf-8',
            //'headerCharset' => 'utf-8',
        ],
    ],

To send a test email and debug your smtp settings, you can use the following command:

$ ./bin/cake passbolt send_test_email

When an email is sent, it is first 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. Add the following line to you crontab:

 * * * * * su -c "/var/www/passbolt/bin/cake EmailQueue.sender >> /var/log/passbolt.log" -s /bin/bash nginx

2. Configure https

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.

In the following steps, we’ll generate a self signed certificate and configure nginx and passbolt to use https.

a. Generate the self signed certificate

$ openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 -subj "/C=FR/ST=Denial/L=Springfield/O=Dis/CN=passbolt.dev" -keyout /etc/ssl/certs/passbolt.key -out /etc/ssl/certs/passbolt.crt

Generating a 4096 bit RSA private key
................++
...++
writing new private key to '/etc/ssl/certs/passbolt.key'
-----

b. Make sure the certificate is readable by nginx

$ chown root:nginx /etc/ssl/certs/passbolt.crt
$ chown root:nginx /etc/ssl/certs/passbolt.key
$ chmod 640 /etc/ssl/certs/passbolt.crt
$ chmod 640 /etc/ssl/certs/passbolt.key

c. Configure ssl in nginx

Let’s add the rewrite and SSL rules and certificates.

$ vi /etc/nginx/conf.d/default.conf

Add this to your file, or replace the whole current content.

server {
  listen 443;
  server_name passbolt.dev;
  ssl on;
  ssl_certificate     /etc/ssl/certs/passbolt.crt;
  ssl_certificate_key /etc/ssl/certs/passbolt.key;
  ssl_protocols TLSv1.2;
  ssl_prefer_server_ciphers on;
  ssl_ciphers ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS;
  ssl_session_tickets off;
  root /var/www/passbolt;
  
  location / {
    try_files $uri $uri/ /index.php?$args;
    index index.php;
  }
  
  location ~ \.php$ {
    fastcgi_index           index.php;
    fastcgi_pass            127.0.0.1:9000;
    fastcgi_split_path_info ^(.+\.php)(.+)$;
    include                 fastcgi_params;
    fastcgi_param           SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param           SERVER_NAME $http_host;
  }
       
  location ~* \.(jpe?g|woff|woff2|ttf|gif|png|bmp|ico|css|js|json|pdf|zip|htm|html|docx?|xlsx?|pptx?|txt|wav|swf|svg|avi|mp\d)$ {
    access_log off;
    log_not_found off;
    try_files $uri /webroot/$uri /index.php?$args;
  }
}

d. Restart Nginx

$ systemctl restart nginx

e. Force SSL in passbolt configuration We’ll need to change the passbolt configuration to make him use https instead of http, and force the redirection to https:

$ vi /var/www/passbolt/config/passbolt.php

Set fullBaseUrl to https

'App' => [
    'fullBaseUrl' => 'https://passbolt.dev',
],

Set ssl.force config parameter to true, instead of false. You can also remove the line as it will be set to true by default.

'ssl' => [
    'force' => true,
],

That’s it! Passbolt is now ready to be used with https.

If you have already done the setup of your user, you will notice that passbolt tells you that the plugin is not configured to work with this domain. This is normal since it was already configured to work with http, and not https.

That’s not an issue, you can fix this easily by clicking on “recover an existing account”

That’s it

Do let us know if you run into problems following this tutorial on the https://community.passbolt.com/c/installation-issues.

Thank you for trying out Passbolt CE!

Troubleshooting

Here are some frequently asked questions related to passbolt installation:

Feel free to ask for help on the community forum.

Last updated

This article was last updated on April 9th, 2018.

Are you experiencing issues when installing passbolt?

Ask the community!

Something is not accurate in this documentation? You can contribute by opening an issue or making pull requests!

View on github

Don't want the hassle of a manual installation? Passbolt Pro comes with out of the box install scripts and a ready-to-use VM.

Get Passbolt Pro