Migrate to a new Virtual Appliance Server

Pro

Passbolt Pro provides a virtual appliance in OVA format. Users can import this appliance on their private virtualization platform and start enjoying Passbolt Pro. The VM includes the following software:

• Debian 12
• Nginx
• Php-fpm
• Mariadb
• Passbolt Pro Preinstalled
• certbot

1. Getting started with Passbolt Pro VM

1.1 Download

Download the ova and the SHA512SUM.txt:

• Passbolt Pro VM
• SHA512SUM.txt

Import the ova file using virtualbox, vmware (ESXi >= 6.0) or any other platform that supports import OVA files.

Once imported, it is highly recommanded to check if the VM is actually running as Debian (64-bit). In order to do that, just open VM's settings and it should show on which version it is running on. Now, you should be able to boot the VM and just point to the VM ip address with their web browser to initiate the passbolt install process.

1.2 Credentials

The appliance performs some actions on the first boot:

• Creates ssh host keys
• Enables ssh
• Creates a set of random mariadb credentials for the mariadb server installed on the appliance
• Creates an empty database where passbolt can be installed.

For the first login the appliance comes with the following ssh default credentials:

VM login credentials:
username: passbolt
password: admin

The passbolt user is part of sudo group. There is no root password, so you cannot login in as root. You can however create a shell as root with the default user:

sudo -s

1.3 Configure HTTPS

Pro tip

If you prefer to proceed to the HTTP installation and re-configure HTTPS later this is likely the standard process so you don't need to follow this section.

You will need to create a file containing the subscription key in /etc/passbolt/subscription_key.txt and change the ownership to www-data

sudo chown www-data:www-data /etc/passbolt/subscription_key.txt

When it comes to SSL, the virtual appliance uses passbolt debian package. Depending on your needs there are two different options to setup HTTPS:

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

2. Configure passbolt

Before you can use the application, you need to configure it. Point your browser to the hostname / ip where passbolt can be reached. You will reach a getting started page.

fig. Passbolt welcome page before configuration

2.1. Healthcheck

The first page of the wizard will tell you if your environment is ready for passbolt. Solve issues if any and click on "Start configuration" when ready.

fig. Wizard - Healthcheck

2.2. Subscription Key

At this step, the wizard will ask you for your subscription key. You should have received it by email soon after your online purchase. Enter it in the box.

fig. Wizard - Subscription Key

2.3. Database

Passbolt Virtual Appliance comes with a preinstalled mariadb database. The credentials for this database are randomly generated on the first boot and the webinstaller autofills those credentials for you.

The autogenerated database credentials will be available for later use by administrators in /etc/passbolt/passbolt.php file.

If you decide to use the autogenerated credentials you can click the "Next" button and move to the next step on this tutorial.

fig. Wizard - Database

Optional: In case you do not want to use the autogenerated mariadb credentials you could connect through ssh to your instance and use the mariadb root credentials to create a new user, password and database for passbolt to use:

ssh admin@your_domain|instance_ip

You can find the root database credentials in /root/.mysql_credentials file:

sudo cat /root/.mysql_credentials

Once you have the root database credentials you can connect to the local mariadb and create any database and user you want to use to install passbolt.

2.4. GPG Key

In this section you can either generate or import a GPG key pair. This key pair will be used by passbolt API to authenticate itself during the login handshake process. Generate a key if you don't have one.

fig. Wizard - Gpg Key

Optional

Import a key if you already have one and you want your server to use it.

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]

fig. Wizard - Import a Key Pair

2.5. Mail Server (SMTP)

At this stage, the wizard will ask you to enter the details of your SMTP server.

fig. Wizard - SMTP Mail Server Details

You can also test that your configuration is correct by using the test email feature at the right of your screen. Enter the email address at which you want the wizard to send you a test email and click on "Send test email".

fig. Wizard - Test SMTP Settings

2.6. Preferences

The wizard will then ask you what preferences you prefer for your instance of passbolt. The recommended defaults are already pre-populated but you can also change them if you know what you are doing.

fig. Wizard - Preferences

2.7. First User Creation

You need to create the first admin user account. This first admin user is probably you, so enter your details and click on next.

fig. Wizard - First user creation

2.8. Installation

That's it. The wizard has now enough information to proceed with the configuration of passbolt. Sit back and relax for a few seconds while the configuration process is going on.

fig. Wizard - Installation

Your user account is now created. You will see a redirection page for a few second and then will be redirected to the user setup process so that you can configure your user account.

fig. Wizard - Completion and Redirection

2.9. HTTPS setup process

Passbolt Pro VM uses passbolt debian package. Depending on your needs there are two different options to setup nginx and SSL using the debian package:

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

Migrate data

Load the backup files into the new server, for the following tasks we will consider that the backup files are in your user home directory ~/backup

You should have:

• Your subscription key
• The private and public GPG keys
• Your database dump
• The avatar archive file passbolt-avatars.tar.gz if you are coming from Passbolt prior to 3.2

Step 1. Create the subscription key file

You received your subscription key by email, copy it as `/etc/passbolt/subscription_key.txt` on your server.

Step 2. Restore Passbolt configuration file and ensure rights and ownership are correct:

sudo mv ~/backup/passbolt.php /etc/passbolt
sudo chown www-data:www-data /etc/passbolt/passbolt.php
sudo chmod 440 /etc/passbolt/passbolt.php
sudo chown www-data:www-data /etc/passbolt/subscription_key.txt

Pro tips: If you didn't the old server database credentials while configuring MariaDB, you might want to update Datasources from /etc/passbolt/passbolt.php

Step 3. Restore GPG public and private keys and ensure rights and ownership are correct:

sudo mv ~/backup/serverkey.asc /etc/passbolt/gpg
sudo mv ~/backup/serverkey_private.asc /etc/passbolt/gpg
sudo chown www-data:www-data /etc/passbolt/gpg/serverkey_private.asc
sudo chown www-data:www-data /etc/passbolt/gpg/serverkey.asc
sudo chmod 440 /etc/passbolt/gpg/serverkey.asc
sudo chmod 440 /etc/passbolt/gpg/serverkey_private.asc

Step 4. Extract the passbolt-avatars.tar.gz archive and set correct rights (if coming from Passbolt version prior to 3.2)

sudo tar xzf passbolt-avatars.tar.gz -C /usr/share/php/passbolt/
sudo chown -R www-data:www-data /usr/share/php/passbolt/webroot/img/public

Step 5. Load the database

mysql -u PASSBOLT_DATABASE_USER -p PASSBOLT_DATABASE < passbolt-backup.sql

Step 6. Import the server key

sudo su -s /bin/bash -c "gpg --home /var/lib/passbolt/.gnupg --import /etc/passbolt/gpg/serverkey_private.asc" www-data

Step 7. Migrate passbolt to the latest version

sudo -H -u www-data /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt migrate"

Step 8. Test passbolt

Try to access your passbolt application with your browser.

If you are encountering any issues, you can run the following command to assess the status of your instance:

sudo -H -u www-data /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt healthcheck"