Skip to main content

Backing up a docker Passbolt installation


Making regular backups is a critical aspect of managing a passbolt instance. Because passbolt stores important information, it is equally important to have a backup strategy in place.

As a passbolt administrator it is your responsibility to define how often and when to perform backups. Please automate and customize this process to match the needs and policies of your organization.

Here are some best practices to keep in mind:

  • Ensure that the backups are taken at intervals that match your usage
  • Take these backups off-site, or to another environment than the live one
  • Make sure the backup is encrypted and stored in a safe location
  • Practice drills and test the backups to make sure they work

What to backup?

If you are a PRO user, ensure you have a backup of your subscription key.

There are also several elements you need to backup:

We assume here Passbolt container is named passbolt-container and MariaDB container database-container. Please replace these names with your own. You can use docker ps for this.

Please Note

Many docker users use -ti, -it or -t -i arguments to execute commands on docker containers. To get reliable backups on docker, please use only -i, as -t will create a pseudo-tty and make your backup files unusuable.

1. The database

This can be easily scripted using mysqldump. Use docker exec to connect to the Passbolt database container and write mysqldump output to a local file.

Be sure to use simple-quotes for the bash -c argument to be able to use MYSQL_USER, MYSQL_PASSWORD and MYSQL_DATABASE environment variables.

docker exec -i database-container bash -c \
> /path/to/backup.sql

2. The server public and private keys

You can use docker cp to backup the Passbolt GPG keys:

docker cp passbolt-container:/etc/passbolt/gpg/serverkey_private.asc \
docker cp passbolt-container:/etc/passbolt/gpg/serverkey.asc \

3. The application configuration

Passbolt docker stores its configuration as environment variables.

If you are using docker compose, environment variables are on the env folder:

  • env/passbolt.env
  • env/mysql.env

If you are running docker container, you should have passed these variables through the command line. Please check the passbolt env variable reference

4. The avatars

Since Passbolt 3.2

User's avatars are no longer stored on disk but on the avatars table of passbolt database.

docker exec -i passbolt-container \
tar cvfzp - -C /usr/share/php/passbolt/ webroot/img/avatar \
> passbolt-avatars.tar.gz

Backup list

At the end of the backup process you should have:

  • a dump of your database
  • the server public and private GPG keys
  • a copy of your config/passbolt.php configuration file
  • a copy of your avatar folder (only if Passbolt version < 3.2)

Migrate the back-up to the new server

We will still consider that the backup files are in your user home directory ~/backup

On the original server

Use a tool such as tar to compress the backup directory

tar -cvzf /home/backup.tar.gz /home/backup

You should copy the compressed backup file to the new server. Use a tool such as scp to do it

scp /home/backup.tar.gz 

On the new server

The compressed backup file should appears inside your home directory, we will extract using a tool such as tar

tar -xzvf /home/backup.tar.gz -C /home/backup

The uncompressed backup file are now available inside your home directory.

What about the secret keys of my collaborators?

Every user private key should also be backed up, this is however not something we/you can automate easily for now (passbolt might provide a functionality for this in the future). We believe it is best if this is the responsibility of the end user. There is a dedicated step during the extension setup to that purpose.

As an administrator you should stress the importance of backing up secret keys to other users. For example this warning could be part of the initial information message sent to introduce passbolt to new users.

It is possible that having users back up their own keys may not be realistic or desirable in your case. In this case you can opt in for an alternative strategy such as setting up the account with/for them and taking a backup of the secret keys then. In the worst case scenario you could automate the process by installing a script on your users machine that would make that backup for you.