How to Install Passbolt with PostgreSQL on Ubuntu 22.04 Server

Passbolt is an open-source self-hosted password manager, which allows you to securely store and share login credentials of website, router password, Wi-Fi password, etc. This tutorial will be showing you how to install Passbolt Community Edition (CE) on Ubuntu 22.04 with the PostgreSQL database server, which is usually faster than MariaDB/MySQL database server.

Passbolt Features

  • Free & open source
  • Passwords are encrypted with OpenPGP, a proven cryptographic standard.
  • Browser extensions are available for Firefox, Google Chrome, Microsoft Edge, and Brave Browser.
  • Mobile app is available for iOS and Android.
  • Easily share login credentials with your team without compromising security.
  • Clean, user-friendly interface.
  • Import and export passwords. You can export your passwords to .kdbx or .csv file format for use with KeepassX, LastPass or 1password.
  • You can manually add login credentials.

Warning: Passbolt compatibility with PostgreSQL is experimental. If you don’t want to risk your data, use MariaDB/MySQL database.

Requirements

It’s very important that your server can send emails, so you can recover your Passbolt account if you forget the password. Follow the tutorial linked below to set up SMTP relay on Ubuntu.

You also need a domain name, so you will be able to securely access Passbolt from anywhere with a web browser. I registered my domain name from NameCheap because the price is low and they give whois privacy protection free for life.

After the above requirements are met, follow the instructions below to install Passbolt.

Step 1: Download Passbolt onto Your Ubuntu 22.04 Server

If you go to the official website to download Passbolt, you are required to enter your name and email address. If that’s not what you like, then download the latest stable version from Github by executing the following commands on your server.

sudo apt install git
 
 sudo mkdir -p /var/www/
 
 sudo chown www-data:www-data /var/www/ -R
 
 cd /var/www/
 
 sudo -u www-data git clone https://github.com/passbolt/passbolt_api.git

The files will be saved in passbolt_api directory. We rename it to passbolt.

sudo mv passbolt_api passbolt

Then make the web server user (www-data) as the owner of this directory.

sudo chown -R www-data:www-data /var/www/passbolt

Run the following command to install PHP modules required or recommended by Passbolt

sudo apt install php-imagick php-gnupg php8.1-common php8.1-mysql php8.1-fpm php8.1-ldap php8.1-gd php8.1-imap php8.1-curl php8.1-zip php8.1-xml php8.1-mbstring php8.1-bz2 php8.1-intl php8.1-gmp php8.1-xsl

Then restart Apache. (If you use Nginx, you don’t need to restart Nginx.)

sudo systemctl restart apache2

Change directory.

cd /var/www/passbolt/

Install Composer – the PHP dependency manager.

sudo apt install composer

Create cache directory for Composer.

sudo mkdir -p /var/www/.composer

Make www-data as the owner.

sudo chown -R www-data:www-data /var/www/.composer

Use Composer to install dependencies.

sudo -u www-data composer install --no-dev

If it asks you to set folder permissions, choose Y.

Step 2: Create a Database and User for Passbolt

Run the following command to install Postgresql database server. PostgreSQL and MariaDB can run on the same server. You don’t need to remove MariaDB.

sudo apt install -y postgresql postgresql-contrib

Install PostgreSQL PHP module.

sudo apt install php8.1-pgsql

Log into PostgreSQL as the postgres user.

sudo -u postgres psql

Create the passbolt database.

CREATE DATABASE passbolt TEMPLATE template0 ENCODING 'UNICODE';

Create a user.

CREATE USER passbolt WITH PASSWORD 'passbolt_password';

Grant permissions to the database user.

ALTER DATABASE passbolt OWNER TO passbolt;
 
 GRANT ALL PRIVILEGES ON DATABASE passbolt TO passbolt;

Press Ctrl+D to log out of PostgreSQL console.

Run the following command to test if you can log in to PostgreSQL.

psql -h 127.0.0.1 -d passbolt -U passbolt -W

Step 3: Generate OpenPGP Key

If you are using a VPS (Virtual Private Server), it’s recommended to install the haveged package to generate enough entropy.

sudo apt install haveged

The haveged.service will automatically start after installation. You can check its status with:

sudo systemctl status haveged

Then run the following command to generate a new key pair.

sudo -u www-data gpg --quick-gen-key --pinentry-mode=loopback 'first_namelast_name <[email protected]>' default default never
  • Enter your first name and last name.
  • Replace [email protected] with your real email address.
  • Don’t leave out the angle bracket.

Like this:

sudo -u www-data gpg --quick-gen-key --pinentry-mode=loopback 'Xiao Guoan <[email protected]>' default default never

If you are asked to set a passphrase, skip it by pressing Enter, because the php-gnupg module doesn’t support using passphrase at the moment.

Copy the private key to the passbolt configuration location.

sudo -u www-data gpg --armor --export-secret-keys [email protected] | sudo tee /var/www/passbolt/config/gpg/serverkey_private.asc > /dev/null

And copy the public key as well.

sudo -u www-data gpg --armor --export [email protected] | sudo tee /var/www/passbolt/config/gpg/serverkey.asc > /dev/null

If GPG produces the following warning, it might be that there are multiple GPG keys for the same email address. You should use a unique email address.

gpg: WARNING: nothing exported

Initialize the www-data user’s keyring.

sudo su -s /bin/bash -c "gpg --list-keys" www-data

Step 4: Configure Passbolt

Make sure you are in /var/www/passbolt/ directory.

cd /var/www/passbolt/

Copy the sample configuration file to a production configuration file.

sudo cp config/passbolt.default.php config/passbolt.php

Edit the configuration file with a command-line text editor, such as Nano.

sudo nano config/passbolt.php

First, find the following line.

'fullBaseUrl' => 'https://www.passbolt.test',

Replace the URL with your own URL, like https://passbolt.yourdomain.com. Don’t forget to create DNS A record for this subdomain in your DNS zone editor.

In the database configuration section, enter the database name, database username and password you created in step 2.

 // Database configuration.
 'Datasources' => [
 'default' => [
 'host' => 'localhost',
 'driver' => \Cake\Database\Driver\Postgres::class,'port' => '5432',
 'username' => 'user',
 'password' => 'secret',
 'database' => 'passbolt',
 ],
 ],

Please note that you need to add the following two lines to tell Passbolt to use PostgreSQL instead of MariaDB.

'driver' => \Cake\Database\Driver\Postgres::class,
 'port' => '5432',

In the email configuration section,

  • Specify the SMTP hostname, port number, login credentials, so your passbolt can send emails. Usually, you need to use port 587 to sumbit emails to remote SMTP server. Make sure you set tls to true, so the SMTP transaction will be encrypted. If you use the free Sendinblue SMTP relay service, then enter your Sendinblue credentials here.
  • Also set the From: email address and From name. For example, I set the From: address to [email protected], so Passbolt will use [email protected] to send notification emails to users.
 // Email configuration.
 'EmailTransport' => [
 'default' => [
 'host' => 'smtp-relay.sendinblue.com',
 'port' => 587,
 'username' => 'smtp_username',
 'password' => 'smtp_password',
 'tls' => true,
 //'client' => null,
 ],
 ],
 'Email' => [
 'default' => [
 'from' => ['[email protected]' => 'Passbolt'],
 //'headerCharset' => 'utf-8',
 ],
 ],
 

Follow the tutorial linked below to set up SMTP relay on Ubuntu.

Hint 1: If passbolt is installed on the same box as your mail server, then you don’t need to specify the username and password in the EmailTransport. Simply use // to comment out these two lines. The following screenshot shows a sample configuration for this scenario.


Hint 2: Don’t forget to add Passbolt Cron job (step 9), or Passbolt won’t send emails.

In the gpg section, enter the GPG key fingerprint like below. You need to delete all whitespaces in the fingerprint.

'fingerprint' => '33B2E593371DE65A35C0B90B5A1F3AF795D461A7',

You can get your key fingerprint with the following command. Replace [email protected] with your email address when generating the PGP key pair.

sudo su -s /bin/bash -c "gpg --list-keys" www-data

After entering the fingerprint, uncomment the following two lines.

'public' => CONFIG . 'gpg' . DS . 'serverkey.asc',
 'private' => CONFIG . 'gpg' . DS . 'serverkey_private.asc',

Save and close the file.

Step 5: Run the Install Script

Run the install script as the www-data user.

sudo su -s /bin/bash -c "/var/www/passbolt/bin/cake passbolt install --force" www-data

Hint: If there are a lot of deprecated errors, you can ignore them.

During the installation, you will be asked to create an admin account. (Note that the admin email address is not the Passbolt notification email address.)

Once you create an account, you will be provided an URL to finish the installation in web browser. Before doing that, we need to configure the web server using Apache or Nginx.

Step 6: Create Apache Virtual Host or Nginx Config File for Passbolt

Apache

If you prefer to use Apache web server, install Apache.

sudo apt install apache2

Create a virtual host for Passbolt.

sudo nano /etc/apache2/sites-available/passbolt.conf

Put the following text into the file. Replace passbolt.example.com with your real domain name and don’t forget to set DNS A record for it. Also note that the web root for Passbolt is /var/www/passbolt/webroot/, not /var/www/passbolt/.

<VirtualHost *:80>
 ServerName passbolt.exmaple.com
 DocumentRoot /var/www/passbolt/webroot/
 
 ErrorLog ${APACHE_LOG_DIR}/error.log
 CustomLog ${APACHE_LOG_DIR}/access.log combined
 
 <Directory />
 Options FollowSymLinks
 AllowOverride All
 </Directory>
 
 <Directory /var/www/passbolt/>
 Options FollowSymLinks MultiViews
 AllowOverride All
 Order allow,deny
 allow from all
 </Directory>
 
 </VirtualHost>

Save and close the file. Then enable this virtual host with:

sudo a2ensite passbolt.conf

Reload Apache for the changes to take effect.

sudo systemctl reload apache2

Nginx

If you use Nginx web server, install Nginx.

sudo apt install nginx

Create a virtual host for Passbolt.

sudo nano /etc/nginx/conf.d/passbolt.conf

Put the following text into the file. Replace passbolt.example.com with your real domain name and don’t forget to set DNS A record for it. Also note that the web root for Passbolt is /var/www/passbolt/webroot/, not /var/www/passbolt/.

server {
 listen 80;
 listen [::]:80;
 server_name passbolt.example.com;
 
 root /var/www/passbolt/webroot/;
 error_log /var/log/nginx/passbolt.error;
 access_log /var/log/nginx/passbolt.access;
 
 index index.php index.html index.htm index.nginx-debian.html;
 
 location / {
 try_files $uri $uri/ /index.php?$query_string;
 }
 
 location ~ \.php$ {
 # try_files $uri =404;
 fastcgi_split_path_info ^(.+\.php)(/.+)$;
 # NOTE: You should have "cgi.fix_pathinfo = 0;" in php.ini
 
 fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
 fastcgi_index index.php;
 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
 include fastcgi_params;
 
 fastcgi_buffer_size 128k;
 fastcgi_buffers 256 16k;
 fastcgi_busy_buffers_size 256k;
 fastcgi_temp_file_write_size 256k;
 }
 
 # Don't log favicon
 location = /favicon.ico {
 log_not_found off;
 access_log off;
 }
 
 # Don't log robots
 location = /robots.txt {
 access_log off;
 log_not_found off;
 }
 
 # Deny all attempts to access hidden files/folders such as .htaccess, .htpasswd, .DS_Store (Mac), etc...
 location ~ /\. {
 deny all;
 access_log off;
 log_not_found off;
 }
 
 # Deny all grunt, composer files
 location ~* (Gruntfile|package|composer)\.(js|json)$ {
 deny all;
 access_log off;
 log_not_found off;
 }
 
 # A long browser cache lifetime can speed up repeat visits to your page
 location ~* \.(jpg|jpeg|gif|png|webp|svg|woff|woff2|ttf|css|js|ico|xml)$ {
 access_log off;
 log_not_found off;
 expires 360d;
 }
 }
 

Save and close the file. Then test Nginx configuration.

sudo nginx -t

If the test is successful, reload Nginx for the changes to take effect.

sudo systemctl reload nginx

Step 7: Enabling HTTPS

To encrypt the HTTP traffic, we can enable HTTPS by installing a free TLS certificate issued from Let’s Encrypt. Run the following command to install Let’s Encrypt client (certbot) on Ubuntu 22.04 server.

sudo apt install certbot

If you use Nginx, then you also need to install the Certbot Nginx plugin.

sudo apt install python3-certbot-nginx

Next, run the following command to obtain and install TLS certificate.

sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d passbolt.example.com

If you use Apache, install the Certbot Apache plugin.

sudo apt install python3-certbot-apache

And run this command to obtain and install TLS certificate.

sudo certbot --apache --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d passbolt.example.com

Where

  • --nginx: Use the nginx plugin.
  • --apache: Use the Apache plugin.
  • --agree-tos: Agree to terms of service.
  • --redirect: Force HTTPS by 301 redirect.
  • --hsts: Add the Strict-Transport-Security header to every HTTP response. Forcing browser to always use TLS for the domain. Defends against SSL/TLS Stripping.
  • --staple-ocsp: Enables OCSP Stapling. A valid OCSP response is stapled to the certificate that the server offers during TLS.

The certificate should now be obtained and automatically installed.

Step 8: Finish Passbolt Installation in Web Browser

First, you need to install the Passbolt extension on your Firefox or Google Chrome browser.

Now copy the URL you got after running the install script and paste it in your browser’s address bar. You will see the web-based set up wizard.

The first step is to create a passphrase.

Then download the recovery kit.

Next, create a custom security token.

Now Passbolt is installed successfully, you can create password, import password from csv or kdbx file.

Step 9: Set Up Cron Job to Automatically Send Emails

To send system emails, run the following command.

sudo -u www-data /var/www/passbolt/bin/cake EmailQueue.sender

You should add the command in www-data user’s Crontab file to automatically process emails.

sudo crontab -u www-data -e

Add the following line in the file to process emails every minute.

* * * * * /var/www/passbolt/bin/cake EmailQueue.sender

Save and close the file.

Step 10: Fixing the Database Encoding Error

The default Passbolt files are made for MySQL/MariaDB, which has two UTF-8 encoding formats:

  • utf8: incomplete UTF-8 support
  • utf8mb4: full UTF-8 support

By default, Passbolt uses utf8mb4. However, in PostgreSQL, there’s only one UTF8 format, namely utf8. If you can find the following logs in /var/log/postgresql/ directory.

[email protected] ERROR: invalid value for parameter "client_encoding": "utf8mb4"
 [email protected] STATEMENT: SET NAMES 'utf8mb4'
 [email protected] ERROR: invalid value for parameter "client_encoding": "utf8mb4"
 [email protected] STATEMENT: SET NAMES 'utf8mb4'
 [email protected] ERROR: invalid value for parameter "client_encoding": "utf8mb4"
 [email protected] STATEMENT: SET NAMES 'utf8mb4'
 [email protected] ERROR: invalid value for parameter "client_encoding": "utf8mb4"
 [email protected] STATEMENT: SET NAMES 'utf8mb4'

It means PostgreSQL doesn’t accept the utf8mb4 format. You need to configure Passbolt to use utf8.

sudo nano /var/www/passbolt/config/app.php

Find the following line:

'encoding' => env('DATASOURCES_DEFAULT_ENCODING','utf8mb4'),

Change it to:

'encoding' => env('DATASOURCES_DEFAULT_ENCODING','utf8'),

Save and close the file.

How to Migrate From MariaDB to PostgreSQL

If you have already installed Passbolt with MariaDB, and now you want to use PostgreSQL, you can

  1. Export the passwords from the original installation as a kdbx file.
  2. Install Passbolt with PostgreSQL.
  3. Import the passwords (kdbx file) to the new Passbolt installation.

How to Update Passbolt

Before updating Passbolt, you should make a backup of the database. The following command will dump the passbolt database as a .sql file.

sudo -u postgres pg_dump passbolt > passbolt.sql

Passbolt provides an update script, which can be invoked with:

sudo su -s /bin/bash -c "/var/www/passbolt/bin/update" www-data

(Optional) Setting Up ModSecurity

You may also want to set up the ModSecurity web application firewall to protect your PHP web applications from hacking. If you use Apache web server on Debian/Ubuntu, then read the following tutorial.

If you use Nginx web server on Debian/Ubuntu, then read the following tutorial:

TroubleShooting

If you are trying to create a password, but are stuck at the “take a deep breath and enjoy being in the present moment
” screen, it’s likely because there’s something wroing in your Apache or Nginx configuration file. If you copy the Apache/Nginx configuration from the article, you should have no problem when creating password.

If you enabled ModSecurity web application firewall, and you see the Could not verify the server key error.

then you need to add the following custom rule exclusion in ModSecurity.

SecRule REQUEST_URI "@streq /auth/verify.json?api-version=v2" "id:1060,phase:2,ctl:ruleRemoveById=942100"

And restart your web server.

sudo systemctl restart apache2

or

sudo systemctl restart nginx

How to Back Up and Restore Passbolt Database

Dump the database into a tar archive with the pg_dump command line utility.

sudo -u postgres -i pg_dump -F t passbolt > passbolt_pgsql.tar

Restore the database with the pg_restore command-line utility.

sudo -u postgres -i pg_restore --clean --dbname=passbolt /path/to/the/passbolt_pgsql.tar

To back up the /var/www/passbolt/ folder, I recommend using Duplicati.

Wrapping Up

I hope this tutorial helped you install Passbolt on Ubuntu 22.04. As always, if you found this post useful, then subscribe to our free newsletter to get more tips and tricks. Take care 🙂

Rate this tutorial
[Total: 5 Average: 5]

13 Responses to “How to Install Passbolt with PostgreSQL on Ubuntu 22.04 Server”

  • Jean-Christophe Vassort
    2 months ago
    Reply

    Hi,

    passbolt developer here, please don’t follow this tutorial.

    * Install passbolt from sources is definitively not the “good way”. Most of the users who never used Linux ran commands as root and corrupt passbolt internal cache system and GPG keyring. We have packages for most Linux distros (https://help.passbolt.com/hosting/install), and Ubuntu 22.04 will be ready in the coming weeks. We are working on it.
    * passbolt is not yet fully compatible with PHP 8.x, you will encounter weird errors on some passbolt pages. We are currently fixing this to provide a full PHP 8 support but it is not ready yet for production.
    * Export password as kdbx is not the right way to migrate to PostreSQL. Any password non-shared with you will be missing, and you will loose rights set on resource passwords (owner, update, read). The correct MariaDB –> PostgreSQL migration procedure is described on our blog post: https://blog.passbolt.com/how-to-configure-passbolt-with-postgresql-experimental-1b9cbe3e56b5

    Cheers,

    • Install Possbolt from the package isn’t a good way either.

      1. The package uses a database configuration wizard to set up the database. However, when you upgrade Ubuntu to the next version, you might have problems updating the database, resulting upgrade failure. Almost everytime.

      2. As the Passbolt help page says, use this package only on a clean fresh server. If you have existing applications, this package might delete the existing data.

      If you are a Linux newbie with a fresh clean server, you can try the official package. I’m just showing you an alternative way which some users might prefer.

      If you find Passbolt is broken on some pages, you can install PHP7.4 on the same server without breaking PHP8.1.
      How to Install Multiple Versions of PHP on Ubuntu

    • Actually, this tutorial is requested by one of my followers, because he doesn’t like the official documentation and wants to learn the ins and outs.

  • Jean-Christophe Vassort
    2 months ago
    Reply

    Hi Xiao,

    I understand your point. I followed your tutorial and I can confirm it is working 👍.

    My feedback from both passbolt pro users and community users regarding the installation from source:

    * Once installed, users never update their instance
    * Even if the tutorial show the correct commands to execute, users execute them as root, and passbolt tmp and gpg keyrings folder are then owned by root. Because of this, it can happen emails are not sent because of bad file ownership. On some other cases, users are not able to connect or create passwords because of this.
    * the more an installation procedure is long and complex, the more users will miss informations and will skip needed steps, I have many users who didn’t setup cronjob, because it is at the end of the tutorial.

    Senior Linux admins know what they are doing, but there is many newbies who are following “from-source tutorials”, and they don’t know what they are doing. I am pretty sure there is many users who copy paste your SQL command without changing the credentials. If you install other PHP applications on the same server such as Nextcloud, WordPress, etc. passbolt DB can be hacked thanks to a not-updated wordpress exploit. passwords won’t be retrieved by the hacker as they are encrypted, but he will be able to drop the tables. And to be honest, most of the newbies don’t have backup strategy.

    That’s why our recommendation is to host passbolt alone without any other application on the server, and with the package, because we ensure all installation steps are done, files ownership are good, and update of the software is easy (apt update && apt upgrade).

    Best,

    • Yes, you are right. There are many Linux newbies who don’t know what they are doing.

      However, if you are a newbie, you probably shouldn’t take charge of mission-critical production servers alone in the first place. You have to learn new skills and can’t stay as a Linux newbie forever.

      If you think it’s best to use one server for one web application, then when you have to install 10 web applications, you need 10 servers. That’s not economical for most users. What about folks who use dedicated servers? Can you afford 10 dedicated servers? As a Linux admin, you must learn skills to properly manage your server.

    • Nextcloud has a built-in web-based updater, which allows users to update the application with a few clicks. Matomo Analytics also has one.

      To make a great user experience, you should consider adding a web-based updater to Passbolt. I know there are many newbie Linux admins who never bother running sudo apt update;sudo apt upgrade periodically.

  • Duffman
    4 weeks ago
    Reply

    Dear @Jean-Christophe Vassort

    Thank you for your work on Passbolt!
    Thank you for making a CE version!
    Sudo apt update would be amazing!
    Hoping Passbolt will be at SCALE 2022, LAX Hilton.
    Congratulations on the 2022 award for best password software!

    I am a noob Linux user and I think LinuxBabe instructions are the best on the internet. They are easy to follow! They always work great!

    I looked at the instruction for Passbolt from you, and as a noob I could not understand your instructions. Docker instruction were ok. But I don’t want to use docker. I want to install from scratch. Native install always works better for me.
    https://blog.passbolt.com/how-to-configure-passbolt-with-postgresql-experimental-1b9cbe3e56b5

    I love how LinuxBabe always teaches user security and proper ways to use permissions.

    I am poor and handicapped and do not have the money to run Passbolt on a separate server. I have a self-hosted server at my apartment. I am very happy LinuxBabe helps the poor users have fun too.

    In regards to miss typing and leaving defaults in db setup.
    that is how I am learning. I have made many mistakes, sometime really stupid ones, but I correct it and keep learning more. Always check your work! User errors are not LinuxBabe errors.

    I want to thank both of you guys from the whole Linux FOSS Community. We love your work and all that you do!

  • Duffman
    4 weeks ago
    Reply

    Great Instructions!!!

    A+

    Thank you LinuxBabe!

  • Ken Wright
    3 weeks ago
    Reply

    I’m hoping this is the right place to ask, but I understand if it isn’t.

    I installed the extensions for both Firefox and Chrome, but the Passbolt installer never sees them. I’ve deleted and reinstalled on both browsers, but the problem remains.

    For reference, I’m using Firefox 100 and Chrome 102.

    • Duffman
      2 weeks ago
      Reply

      i had this issue as well. i deleted plugin, cleared meta data/cookies, closed and reopened browser.
      then go to domain, login, click download plugin again and this time Passbolt should recognize that the plugin is installed.
      I think it is an issue with security and plugins in the browser.

      i hope it works for you too.

      Firefox 100
      Chrome 102

      • Ken Wright
        3 days ago
        Reply

        No joy. It still isn’t detecting the plugin.

        I pressed Ctrl-Shift-Del and selected Cookies and Cache; did I miss something?

    • I remember after verifying the email address, I had to manually type the Passbolt URL in the browser address bar.
      Just https://passbolt.example.com, no more and no less.

      • Ken Wright
        3 days ago
        Reply

        I tried that. It asks me for my email address, and to accept terms. I did this, and it claims to have sent an email to me, but the only thing I’ve received is a link to the URL I got during installation
 and it still doesn’t detect the plugin.

Leave a Comment Cancel reply