How I Set Up Passbolt Password Manager in Docker – A Step-by-Step POC Guide

Introduction

My team needed a self-hosted, open-source password manager that would give us full control over our secrets while enabling secure collaboration. After evaluating options, I decided to explore Passbolt due to its robust security model and team-friendly features.

The goal of this proof-of-concept (POC) was to test Passbolt’s usability, security, and ease of deployment using Docker containers. This setup enables us to run everything in an isolated, portable, and easy-to-replicate manner, which is ideal for both our development and future production environments.

1. What is Passbolt?

Passbolt is an open-source, self-hosted password manager designed specifically for teams. It features:

• End-to-end encryption to keep your secrets safe from prying eyes.

• Built-in team collaboration features that let you share passwords securely.

• Uses GPG keys for encryption, avoiding the traditional master password model, which enhances security and trust.

2. My Setup: Passbolt in Docker

For this POC, I chose a simple but effective tech stack:

• Docker & Docker Compose for container orchestration.

• MariaDB as the database backend.

• MailHog for catching emails locally during initial testing (no real emails sent yet).

• Later, I switched to Gmail SMTP to send real invitation emails once the setup was proven stable.

This approach gave me a controlled environment to experiment and validate Passbolt’s features without risking real user communication during the early stages.

3. Deploying Passbolt with Docker

To get started quickly, I used Docker Compose to orchestrate the necessary services: Passbolt itself, the MariaDB database, and MailHog for email testing.

Here’s the minimal docker-compose.yml I created the initial POC:

yamlCopyEditversion: '3.8'

services:
  db:
    image: mariadb:10.6
    container_name: passbolt_db
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: passbolt
      MYSQL_USER: passbolt
      MYSQL_PASSWORD: Str0ngP@ssw0rd  
    volumes:
      - db_data:/var/lib/mysql

  passbolt:
    image: passbolt/passbolt:latest
    container_name: passbolt
    environment:
      - DATASOURCES_DEFAULT_HOST=db
      - DATASOURCES_DEFAULT_USERNAME=passbolt
      - DATASOURCES_DEFAULT_PASSWORD=Str0ngP@ssw0rd  
      - DATASOURCES_DEFAULT_DATABASE=passbolt
      - PASSBOLT_REGISTRATION_PUBLIC=true
      - APP_FULL_BASE_URL=http://localhost:8080
      - EMAIL_TRANSPORT_DEFAULT_URL=smtp://mail:1025
      - EMAIL_DEFAULT_FROM=noreply@mzurisoft.com
      - EMAIL_DEFAULT_FROM_NAME=Passbolt
    ports:
      - "8080:80"
    volumes:
      - gpg_data:/var/www/passbolt/config/gpg
      - passbolt_data:/var/www/passbolt
    depends_on:
      - db

  mail:
    image: mailhog/mailhog
    container_name: passbolt_mail
    ports:
      - "8025:8025"
    expose:
      - "1025"

volumes:
  db_data:
  gpg_data:
  passbolt_data:

After saving the file, I started the stack with:

docker compose up --build

After that, I ran this command to enter Passbolt’s container :

docker exec -it passbolt /bin/bash

I then created an admin user whose credentials I would use to log into Passbolt :

su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt send_test_email --recipient test@example.com" www-data

---

4. Initial User Invitation & Email Testing with MailHog

Since MailHog captures emails locally, it was perfect for testing without sending real invites.

Here’s what I did:

• Logged into Passbolt’s web interface at http://localhost:8080 as admin

• Invited other team members via the admin dashboard

• Opened MailHog’s web UI at http://localhost:8025 to find and inspect the invitation emails

• Used the invitation link in MailHog to complete the setup for invited users

This step confirmed the invitation and user onboarding process worked flawlessly, all while keeping emails contained locally.

---

5. Moving to Real Email Invitations Using Gmail SMTP

To make the system usable beyond internal testing, I replaced MailHog with Gmail’s SMTP service so users would receive invites in their actual inboxes.

Here’s how I set that up:

Step 1: Enable 2-Step Verification & Create a Gmail App Password

• Enabled 2FA on my Gmail account

• Generated an app password specifically for Passbolt’s SMTP usage

Step 2: Update docker-compose.yml

Removed the MailHog service and replaced the email environment variables in the Passbolt service like this:

environment:
  - EMAIL_TRANSPORT_DEFAULT_URL=smtp://your-email@gmail.com:your-app-password@smtp.gmail.com:587/?tls=true
  - EMAIL_DEFAULT_FROM=your-email@gmail.com
  - EMAIL_DEFAULT_FROM_NAME=Passbolt

Step 3: Restart Containers

docker compose down
docker compose up -d

---

6. Verifying Real Email Delivery & Final Thoughts

After the update, invitations were sent directly through Gmail SMTP, and invited users received emails in their real inboxes without delay or issues.

To monitor email delivery or troubleshoot, I checked the Passbolt logs:

docker logs passbolt

---

Conclusion

Setting up Passbolt in Docker was straightforward, and switching from MailHog to Gmail SMTP made the POC ready for real-world use. This approach gives teams a secure, self-hosted password manager with trusted email delivery.

Would I recommend Passbolt?

✅ Yes, if you want a fully open-source, self-hosted solution that prioritizes security with end-to-end encryption, supports team collaboration, and gives you full control over your data and deployment environment.

❌ No, if you need a turnkey cloud-hosted service with minimal setup, or if your team requires advanced features like built-in SSO without additional configuration, since those may require paid versions or more complex setups.

Final thoughts
Passbolt is an excellent choice for organisations that value transparency, security, and control. Containerising it with Docker simplifies deployment and scaling. With some extra effort on production hardening, such as adding HTTPS and backups, it can serve as a reliable password manager for teams of any size.

Next steps I plan to explore include:

• Integrating Single Sign-On (SSO) for seamless user authentication

• Implementing regular backups for data and encryption keys

If you’re interested in a secure, collaborative password manager that you control fully, Passbolt is a solid choice, especially when containerised for easy deployment.