How to Deploy Passbolt – Team Password Manager

Passbolt is an open-source password manager designed for collaboration. Passbolt focuses on team sharing, utilizing OpenPGP for end-to-end encryption. It features a robust API, rigorous security standards, and a browser-based extension interface.

This article demonstrates how to deploy Passbolt Community Edition on Ubuntu 24.04 using Docker Compose. The stack includes MariaDB for data storage and Traefik for automatic HTTPS termination.

Prerequisites

Before you begin:

• Have access to an Ubuntu 24.04 server as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Configure a domain name, such as passbolt.example.com, to point to your server’s public IP address.

Set Up the Directory Structure and Environment Variables

Passbolt requires persistent storage for its database, GPG keys, and TLS certificates, as well as several environment variables that define its domain and database credentials. Because the official Passbolt container runs as the internal user www-data (UID 33), the directory structure must be created with the correct ownership so the container can generate and store GPG keys without permission errors. This section prepares the required folders and creates the .env file that Docker Compose uses to load configuration values automatically.

1. Create the project folders.

   CONSOLE

   Copy

   $ mkdir -p ~/passbolt/{db,gpg,letsencrypt}

   Explain Code

   Powered by Vultr AgentBeta
   • db - Persistent storage for the MariaDB database.
   • gpg - Stores the server's private PGP keys.
   • letsencrypt - Traefik ACME certificates.

2. Change the ownership of the gpg directory to User ID 33. The Passbolt container runs internally as user ID 33 (www-data). This command grants the container permission to write to the folder, allowing it to generate and save the server's GPG keys.

   CONSOLE

   Copy

   $ sudo chown -R 33:33 ~/passbolt/gpg

   Explain Code

   Powered by Vultr AgentBeta

3. Navigate to the root Passbolt directory.

   CONSOLE

   Copy

   $ cd ~/passbolt

   Explain Code

   Powered by Vultr AgentBeta

Configure Environment Variables

Passbolt requires several environment variables to define its domain, database credentials, and email address for certificate management. These values are stored in an .env file, so Docker Compose can load them automatically during deployment.

1. Create a file named .env in the project directory.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following values:

   INI

   Copy

   DOMAIN=passbolt.example.com
   LETSENCRYPT_EMAIL=admin@example.com
   
   MYSQL_USER=passbolt
   MYSQL_PASSWORD=STRONG_DB_PASSWORD
   MYSQL_DATABASE=passbolt

   Explain Code

   Powered by Vultr AgentBeta

   Replace passbolt.example.com with your domain and STRONG_DB_PASSWORD with a secure password. Save and close the file.

Deploy with Docker Compose

This section sets up the full Passbolt deployment using Docker Compose. The stack includes three services: Traefik for HTTPS termination, MariaDB for persistent data storage, and Passbolt for the main password management application. All services run in isolated containers and communicate over a shared Docker network.

1. Add your user account to the docker user group.

   CONSOLE

   Copy

   $ sudo usermod -aG docker $USER

   Explain Code

   Powered by Vultr AgentBeta

2. Apply new group membership.

   CONSOLE

   Copy

   $ newgrp docker

   Explain Code

   Powered by Vultr AgentBeta

3. Create the Docker Compose manifest file.

   CONSOLE

   Copy

   $ nano docker-compose.yml

   Explain Code

   Powered by Vultr AgentBeta

4. Add the following contents:

   YAML

   Copy

   services:
     traefik:
       image: traefik:latest
       container_name: traefik
       restart: unless-stopped
       environment:
         DOCKER_API_VERSION: "1.44"
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.le.acme.httpchallenge=true"
         - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
         - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock:ro
         - ./letsencrypt:/letsencrypt
   
     db:
       image: mariadb:10.11
       container_name: passbolt-db
       restart: unless-stopped
       environment:
         MYSQL_USER: ${MYSQL_USER}
         MYSQL_PASSWORD: ${MYSQL_PASSWORD}
         MYSQL_DATABASE: ${MYSQL_DATABASE}
         MYSQL_RANDOM_ROOT_PASSWORD: "true"
       volumes:
         - ./db:/var/lib/mysql
       healthcheck:
         test: ["CMD", "mysqladmin", "ping", "--silent"]
         interval: 3s
         retries: 10
         start_period: 30s
   
     passbolt:
       image: passbolt/passbolt:latest
       container_name: passbolt
       restart: unless-stopped
       depends_on:
         db:
           condition: service_healthy
       environment:
         APP_FULL_BASE_URL: https://${DOMAIN}
         DATASOURCES_DEFAULT_HOST: db
         DATASOURCES_DEFAULT_USERNAME: ${MYSQL_USER}
         DATASOURCES_DEFAULT_PASSWORD: ${MYSQL_PASSWORD}
         DATASOURCES_DEFAULT_DATABASE: ${MYSQL_DATABASE}
       volumes:
         - ./gpg:/etc/passbolt/gpg
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.passbolt.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.passbolt.entrypoints=websecure"
         - "traefik.http.routers.passbolt.tls=true"
         - "traefik.http.routers.passbolt.tls.certresolver=le"
         - "traefik.http.services.passbolt.loadbalancer.server.port=80"

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file. This Docker Compose configuration deploys Passbolt, using MariaDB for storage and Traefik for HTTPS termination. Each service plays a distinct role in the deployment:

   passbolt service

   • Runs the main Passbolt application using the official passbolt/passbolt image.
   • Connects to the MariaDB database using the credentials defined in the .env file.
   • Reads the APP_FULL_BASE_URL variable to correctly generate all application URLs.
   • Uses a persistent GPG directory (./gpg) to store Passbolt’s server-side encryption keys.
   • Registers HTTP routing rules with Traefik to serve the application securely over HTTPS at your configured domain (${DOMAIN}).
   • Exposes port 80 internally, while Traefik handles external HTTPS traffic on port 443.
   • Waits for MariaDB to be healthy before starting, preventing database connection errors during migrations.

   db service (MariaDB)

   • Runs MariaDB 10.11, the officially supported database backend for Passbolt.
   • Initializes the Passbolt database using the username, password, and schema defined in the .env file.
   • Stores database files in the ./db directory for persistence across container restarts.
   • Uses MYSQL_RANDOM_ROOT_PASSWORD=true to automatically generate a secure root password.
   • Includes a healthcheck that runs mysqladmin ping to verify database readiness.

   traefik service

   • Listens on ports 80 and 443 to handle all incoming traffic.
   • Automatically provisions and renews TLS certificates via Let’s Encrypt using the ACME HTTP-01 challenge.
   • Reads Docker labels from the Passbolt container to determine routing rules.
   • Redirects all HTTP requests to HTTPS for secure access.
   • Stores generated certificates in the ./letsencrypt directory.

5. Start all services in detached mode.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

6. Check the container status.

   CONSOLE

   Copy

   $ docker compose ps

   Explain Code

   Powered by Vultr AgentBeta

   Note

   For more information on managing a Docker Compose stack, see the How To Use Docker Compose article.

Create the First Administrator

Passbolt does not ship with a default login. You must manually register the first user via the command line to generate an invite link.

1. Execute the following command to register the first user. Replace admin@example.com, FIRSTNAME, and LASTNAME with your details.

   CONSOLE

   Copy

   $ docker compose exec passbolt su -m -c "/usr/share/php/passbolt/bin/cake passbolt register_user -u admin@example.com -f FIRSTNAME -l LASTNAME -r admin" -s /bin/sh www-data

   Explain Code

   Powered by Vultr AgentBeta

   Sample output:

   ...
   User saved successfully.
   To start registration follow the link provided in your mailbox or here:
   https://passbolt.example.com/setup/start/bbfa49fc-ac2e...

2. The output of the last step contains a link. Copy the full URL provided in the terminal and paste it into your web browser to initiate the user registration process.

3. Passbolt detects your browser and prompts you to install the official extension. This is mandatory for local encryption. Install the extension.

4. After you install the extension, the page refreshes and detects the extention. Click Next.

5. Enter a strong passphrase. Click Next.

6. Check the I safely stored my recovery kit. option and click Next.

7. Choose the security token and color. Click Next.

8. The Passbolt dashboard loads.

   

Conclusion

You have successfully deployed Passbolt on Ubuntu 24.04. You now have a secure, team-oriented password manager running with OpenPGP encryption. For more information, refer to the Passbolt documentation.