Docker passbolt installation

System requirements

• Docker CE

Optional system requirements

• MySQL < 8.x or MariaDB as separated containers or host installation.
• docker-compose if you plan to use a docker-compose.yml file to run passbolt container.
• rng-tools/haveged for faster filling of container entropy pool. These tools come handy in cases where GnuPG complains about no entropy is available to perform some operation (generate keys, encrypt, sign…) inside the docker container. Important considerations

1. Getting and running passbolt container

Passbolt containers follow the following tagging:

<version_number>-<build_number>-debian

For convenience we also provide a latest tag for Passbolt containers. Throughout these documented procedures we make use of the latest tag so users will get the last version of passbolt. However, it is recommended that users pull the tags pointing to specific passbolt versions when running in environments other than testing.

Get passbolt latest docker container:

$ docker pull passbolt/passbolt:latest

Using docker-compose

From the docker-compose official docs: ‘Compose is a tool for defining and running multi-container Docker applications’

Passbolt provides a docker-compose.yml file. That users can download and use with docker-compose. The easiest way to use passbolt provided docker-compose.yml is to:

$ git clone https://github.com/passbolt/passbolt_docker
$ cd passbolt_docker

At this point some users might want to customize passbolt environment variables and change the fullBaseUrl for instance. Environment variables are defined in the following files:

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

For further reference regarding environment variables, please see the link at the bottom of the page.

Docker-compose requires the use of sudo. Alternatively, you may choose to add your local user to the docker group. Going forward, the second option is assumed.

Once the files fit your needs it is time to:

$ docker-compose -f docker-compose.yml up

If there are no errors, Ctrl-C to stop the docker-compose script, then run the above command again with a -d flag at the end (to run in detached mode). You can then confirm the processes are running with:

docker-compose ps

Create first admin user using docker-compose

If you run passbolt using docker-compose.yml provided by passbolt:

$ docker-compose exec passbolt su -m -c "/usr/share/php/passbolt/bin/cake \
                                passbolt register_user \
                                -u <[email protected]> \
                                -f <yourname> \
                                -l <surname> \
                                -r admin" -s /bin/sh www-data

Using passbolt container

Passbolt requires a database backend to store the information. In this section we will be using a MariaDB database packaged as a docker container.

Manually run passbolt container and mariadb container

It is recommended to create a user defined network to ease the container name resolution. Using a user defined network will provide a method to access containers using their names instead ip addresses:

$ docker network create passbolt_network

First run the mariadb container:

As we want all the data in mariadb to survive container restarts it is recommended to create either a docker volume or a host directory and mount it at /var/lib/mysql

$ docker volume create mariadb_passbolt_data
$ docker run -d --name mariadb --net passbolt_network \
             --mount source=mariadb_passbolt_data,target=/var/lib/mysql \
             -e MYSQL_ROOT_PASSWORD=<root_password> \
             -e MYSQL_DATABASE=<mariadb_database> \
             -e MYSQL_USER=<mariadb_user> \
             -e MYSQL_PASSWORD=<mariadb_password> \
             mariadb

Now we can run the passbolt container:

$ docker run --name passbolt --net passbolt_network \
             --mount type=bind,\
               source=<host_path_to_gnupg_keys_dir>,\
               target=/etc/passbolt/gpg \
             -p 443:443 \
             -p 80:80 \
             -e DATASOURCES_DEFAULT_HOST=mariadb \
             -e DATASOURCES_DEFAULT_PASSWORD=<mariadb_password> \
             -e DATASOURCES_DEFAULT_USERNAME=<mariadb_user> \
             -e DATASOURCES_DEFAULT_DATABASE=<mariadb_database> \
             -e APP_FULL_BASE_URL=https://mydomain.com \
             passbolt/passbolt:latest

Note: strings between ‘<’ and ‘>’ are variables that the users should fill with their data.

Passbolt requires some data to be persistant, most notably the OpenPGP server keys. However, images and potentially the SSL certificate might also need to be persisted depending on your specific configuration. You can read more about it below.

Persisting data in passbolt container

There are several locations that might be interesting for the users to persist data between container restarts:

• Images directory: /usr/share/php/passbolt/webroot/img
• Gnupg serverkeys directory: /etc/passbolt/gpg
• SSL certificate files: /etc/ssl/certs/certificate.crt /etc/ssl/certs/certificate.key

This files and directories can be persisted in the docker volume using docker volumes or using bind mounts

Examples

An example for persisting the images directory could be to create a docker volume:

$ docker volume create passbolt_images

And run passbolt container with the previously created volume:

$ docker run --name passbolt --net passbolt_network \
             --mount source=passbolt_images,\
             target=/usr/share/php/passbolt/webroot/img \
             -p 443:443 \
             -p 80:80 \
             -e DATASOURCES_DEFAULT_HOST=mariadb \
             -e DATASOURCES_DEFAULT_PASSWORD=<mariadb_password> \
             -e DATASOURCES_DEFAULT_USERNAME=<mariadb_user> \
             -e DATASOURCES_DEFAULT_DATABASE=<mariadb_database> \
             -e APP_FULL_BASE_URL=https://mydomain.com \
             passbolt/passbolt:latest

Bind volumes are usually useful when, for instance, the SSL certificates or GnuPG keys have been already created in the host machine:

$ docker run --name passbolt --net passbolt_network \
             --mount type=bind,\
               source=<host_path_to_gnupg_keys_dir>,\
               target=/etc/passbolt/gpg \
             -p 443:443 \
             -p 80:80 \
             -e DATASOURCES_DEFAULT_HOST=mariadb \
             -e DATASOURCES_DEFAULT_PASSWORD=<mariadb_password> \
             -e DATASOURCES_DEFAULT_USERNAME=<mariadb_user> \
             -e DATASOURCES_DEFAULT_DATABASE=<mariadb_database> \
             -e APP_FULL_BASE_URL=https://mydomain.com \
             passbolt/passbolt:latest

An example of the above using docker-compose can be found here where bind mounts and volumes are used.

NOTE: If you dont provide any GnuPG severkey or SSL certificate passbolt container will create a self signed SSL certificate and a GnuPG server key pair.

Manually creating first admin user

Once the passbolt container is up and running use this command to generate the first admin user:

$ docker exec passbolt su -m -c "/usr/share/php/passbolt/bin/cake \
                                passbolt register_user \
                                -u <[email protected]> \
                                -f <yourname> \
                                -l <surname> \
                                -r admin" -s /bin/sh www-data

It will output a link similar to the below one that can be pasted on the browser to finalize user registration:

https://mydomain.com/setup/install/1eafab88-a17d-4ad8-97af-77a97f5ff552/f097be64-3703-41e2-8ea2-d59cbe1c15bc

More information on environment variables

For more information on which environment variables are available on Passbolt, please check the passbolt env variable reference