Skip to main content

Install Passbolt with an Ansible playbook

CE
Warning

Installing Passbolt using an Ansible playbook is considered to be a very advanced installation method. If you are not very comfortable and familiar with Ansible we strongly recommend that you install via one of our other methods.

info

The Ansible playbook has been tested on Debian 12 and Red Hat 9. We believe that derivatives should also work, but it's important to note that you may encounter unexpected errors if you are not using one of these two distributions.

Prerequisites​

Server​

You will need on the server:

Please note

It is important that you use a vanilla server with no other services or tools already installed on it. The playbook could potentially damage any existing data on your server.

  • A minimal Debian 12 or Red Hat 9 server
  • A domain/hostname pointing to your server (or at least a static IP)
  • A working SMTP server for email notifications
  • Privilege access (sudo or equivalent)

The recommended server requirements are:

  • 2 CPU cores
  • 2 GB RAM

Controller​

You will need on the client where the Ansible playbook is ran from:

  • A supported OS (Linux or macOS)
  • SSHPass (macOS only)
  • Ansible installed
  • An SSH client

Cloning the repository​

The source code of our Ansible playbook is available on GitHub. You will need this repository in order to be able to run the playbook.

Step 1. Clone the Ansible install playbook repository:

git clone [email protected]:passbolt/passbolt-ansible-playbooks

Step 1. Navigate to the playbook directory:

cd passbolt-ansible-playbooks

Configure the inventory​

In order to run the Ansible playbook, you will need to configure the server(s) access for which you are running the playbook against. To do that, you can take a look at the official documentation.

Configure variables​

WARNING

Some environment variable are considered sensitive, we recommend using Ansible-vault for encrypting them.

In order to configure the variables, you can take a look at our README provided in our source code.

Running the Ansible playbook​

When you set all the necessary variables and configured the hosts, you will be able to run the Ansible playbook.

In the main directory file, you can run:

ansible-playbook -i $YOUR_INVENTORY install.yml

After running the playbook, it should display one of multiple registration URLs based on your hosts file. In the example below, passbolt has been installed on a Debian 12 server and is prompting the URL:

TASK [passbolt : Complete the administrator registration on a web browser] ***************************************************

ok: [YOUR_SERVER_IP] => {
  "msg": "In order to complete your full admin registration, please navigate to https://ce.debian12.local/setup/start/089c209e-5518-4240-997d-b1c354e2a450/13067e51-fc61-49ce-b8de-54f5d3fad43e"
}

You will need to copy this URL and paste it to your web browser, then you can follow the next instructions.

Debugging​

If you run into any issues, we would recommend running ansible-playbook -i $YOUR_INVENTORY -vvv and share the output on a dedicated thread on our community forum. Please, make sure that you censor any sensitive information before sending it.

Configure your administrator account​

Download the plugin​

Before continuing passbolt will require you to download its plugin. If you already have it installed you can go to the next step.

Download the browser extension
fig. Download the browser extension

Create a new key​

Passbolt will ask you to create or import a key that will be later use to identify you and encrypt your passwords. Your key needs to be protected by a password. Choose it wisely, it will be the gatekeeper to all your other passwords.

Generate a GPG Key
fig. Generate a key

Download your recovery kit​

This step is essential. Your key is the only way to access your account and passwords. If you lose this key (by breaking or losing your computer and not having a backup for example), your encrypted data will be lost even if you remember your passphrase.

Download the Recovery Kit
fig. Download the Recovery Kit

Define your security token​

Choosing a color and a three characters token is a secondary security mechanism that helps you to mitigate phishing attacks. Each time you are performing a sensitive operation on passbolt, you should see this token.

Define your security token
fig. Define your security token

That's it!​

Your administrator account is configured. You will be redirected to the login page of passbolt. Enjoy!