Mastering Passbolt Containerization: A Deep Dive into Docker and Kubernetes Deployments for Enterprise Secret Management

The modern digital landscape demands robust, secure, and accessible credential management systems that can scale from small development teams to large enterprise organizations. Passbolt has emerged as a premier open-source solution in this space, offering a sovereign, adaptable platform designed for security-conscious IT professionals. While the software is accessible through various installation vectors, the deployment via containerization technologies such as Docker and Docker Compose represents a sophisticated approach that requires a nuanced understanding of system administration, network configuration, and container orchestration. This method, while powerful, is categorized as somewhat advanced, assuming a foundational familiarity with Docker environments and previous experience running applications within containerized ecosystems. For those lacking this specific expertise, alternative installation methods are often recommended to ensure stability and security. The infrastructure underlying a Passbolt deployment involves not just the application container itself, but a cohesive stack including database services, web servers, and critical system utilities. Understanding the intricacies of this stack, from the initial download of configuration files to the final registration of the administrative user, is essential for anyone looking to implement a secure, self-hosted password management solution. The following analysis provides an exhaustive exploration of the Passbolt Docker deployment process, covering system requirements, file verification, configuration customization, image architecture, and manual container orchestration techniques.

System Prerequisites and Environmental Foundation

Before initiating the deployment of Passbolt via Docker, it is imperative to establish a robust foundational environment. The installation method is not a plug-and-play solution for those unfamiliar with container technologies; it assumes the administrator is already proficient in Docker operations and has successfully managed other applications using this platform. The first and most critical requirement is the presence of Docker itself. The Docker engine must be installed and operational on the host system, typically a Linux distribution. The documentation directs users to the official Docker installation guides to ensure the correct version of the Docker engine is acquired. This installation provides the daemon and client tools necessary to build, run, and manage containers. Without a functional Docker installation, the subsequent steps involving image pulling and container orchestration will fail immediately.

Beyond the Docker engine, specific user permissions are required to execute Docker commands efficiently and securely. The system requires a Linux user who is capable of running Docker commands without the need for sudo privileges. This is typically achieved by adding the user to the docker group during the initial setup of the Docker engine. This permission structure is vital for operational efficiency, allowing the administrator to manage the container lifecycle without constantly invoking root privileges, which can pose security risks if mismanaged. The absence of this configuration can lead to permission denied errors during the execution of docker-compose or direct docker run commands.

Furthermore, the operational integrity of the Passbolt instance relies on two external services that must be configured on the host or network level. The first is a working Simple Mail Transfer Protocol (SMTP) server. Passbolt utilizes email notifications for critical security events, such as password sharing requests, account recovery, and audit logs. Without a properly configured SMTP server, users will not receive necessary communications, rendering the shared secret management functionality largely ineffective. The SMTP configuration must be integrated into the Passbolt environment variables during the deployment phase, ensuring that the application can authenticate with the mail server and route emails correctly.

The second critical prerequisite is a working Network Time Protocol (NTP) service. Time synchronization is not merely a convenience in cryptographic systems; it is a fundamental requirement for security. Passbolt utilizes GPG (GNU Privacy Guard) for encryption and authentication. GPG operations, particularly those involving digital signatures and certificate validation, are highly sensitive to time discrepancies. If the system clock on the Docker host drifts significantly from the actual time, GPG authentication issues will arise. These issues can manifest as invalid signatures, expired key errors, or complete failure to authenticate users. Therefore, ensuring that the host system is synchronized with a reliable NTP server is a mandatory step before deploying the Passbolt container stack. Failure to maintain accurate time synchronization can compromise the entire security model of the platform.

Docker Compose: The Recommended Deployment Strategy

While it is possible to deploy Passbolt using manual docker run commands, the documentation explicitly identifies Docker Compose as the easiest and recommended method for deploying the Passbolt stack. Docker Compose allows for the definition and running of multi-container Docker applications. In the context of Passbolt, this typically involves coordinating the Passbolt application container with a database container, such as MariaDB or MySQL, and potentially other sidecar services. The use of Docker Compose simplifies the management of dependencies, network configuration, and environment variables, providing a single source of truth for the entire infrastructure.

The first step in the Docker Compose deployment process involves downloading the official example configuration file. This file serves as the blueprint for the container stack. Administrators are instructed to use the curl utility to retrieve the docker-compose-ce.yaml file directly from the Passbolt download server. The command curl -LO https://download.passbolt.com/ce/docker/docker-compose-ce.yaml initiates this download. The -L flag ensures that curl follows any redirects, while the -O flag saves the file with its original name. This file contains the service definitions, network configurations, and default environment variable mappings required to spin up a basic, functional instance of the Community Edition of Passbolt.

However, downloading a configuration file from the internet introduces the risk of corruption or tampering. To mitigate this, Passbolt provides a cryptographic checksum file that must be used to verify the integrity of the downloaded YAML file. The second download command retrieves this checksum file: curl -LO https://github.com/passbolt/passbolt_docker/releases/latest/download/docker-compose-ce-SHA512SUM.txt. This file contains the expected SHA-512 hash of the docker-compose-ce.yaml file. The SHA-512 algorithm is a cryptographic hash function that produces a unique 512-bit (64-byte) hash value for a given input. Even a minor change in the YAML file, such as a single character modification, will result in a completely different hash.

To perform the verification, the administrator must execute the sha512sum command with the -c flag, pointing to the checksum file. The command sha512sum -c docker-compose-ce-SHA512SUM.txt compares the hash of the local docker-compose-ce.yaml file against the expected hash stored in the .txt file. The expected output of this command is docker-compose-ce.yaml: OK. This confirmation indicates that the file has not been corrupted during the transfer and has not been tampered with. If the output is not correct, or if the command returns an error indicating a mismatch, the downloaded file is considered compromised or corrupted. In such cases, the documentation advises retrying the download steps or seeking support from the community forum. This rigorous verification process is a hallmark of secure software deployment, ensuring that the infrastructure is built on trusted, verified components.

Once the file integrity is confirmed, the next step involves configuring the environment variables within the docker-compose-ce.yaml file. This customization phase is critical for tailoring the instance to the specific needs of the organization. The default docker-compose-ce.yaml file is set to use the latest tag for the Passbolt image, which points to the most recent stable release of the Community Edition. However, administrators may wish to pin to a specific version for stability or to configure specific network ports, database credentials, and the base URL of the application. The environment variables defined in this YAML file are injected into the container at runtime, allowing the Passbolt application to configure its database connections, SMTP settings, and domain name without modifying the application code itself. This separation of configuration from code is a key principle of containerized applications, enabling the same image to be deployed across different environments with different configurations.

Image Architecture and Tagging Strategy

The Passbolt Docker image is hosted on Docker Hub under the repository passbolt/passbolt. The image repository contains a variety of tags, each representing a different version, architecture, or configuration of the software. Understanding these tags is essential for selecting the appropriate image for the deployment environment. The latest tag is the default and points to the most recent release of the software. The image supports multiple architectures, including linux/amd64, linux/arm/v5, and linux/arm/v7. The amd64 image has a size of approximately 147.19 MB, while the ARM variants are slightly smaller, with arm/v5 at 136.59 MB and arm/v7 at 131.09 MB. This multi-architecture support allows Passbolt to be deployed on a wide range of hardware, from standard x86 servers to ARM-based single-board computers like the Raspberry Pi.

The tagging strategy also distinguishes between the Community Edition (CE) and the Professional Edition (Pro). The Community Edition is 100% open source, free as in free beer and free speech, with no strings attached. It is suitable for teams of any size, from five individuals to organizations with thousands of employees. The Professional Edition, indicated by tags containing pro, includes additional features and support options. The tags also indicate whether the image is built for standard Kubernetes environments or OpenShift. The openshift tags, such as 5.11.0-1-ce-openshift, are optimized for the Red Hat OpenShift platform, which has stricter security constraints and different user rights management than standard Docker.

Another critical distinction is the non-root variant. Standard Docker containers often run as the root user by default, which poses a security risk if the container is compromised. The non-root tags, such as 5.11.0-1-ce-non-root and latest-ce-non-root, are built to run the application as a non-privileged user. This reduces the potential impact of a security breach, as the attacker would not have root access within the container. The non-root images are slightly larger, with the latest-ce-non-root image for amd64 being 154.81 MB compared to the standard latest image at 147.19 MB. This increase in size is due to the additional layers and configurations required to set up the non-root user environment.

The versioning scheme follows a semantic versioning pattern, with tags like 5.11.0-1-ce indicating the major, minor, and patch versions of the software. The 1 in 5.11.0-1-ce likely indicates the build number or a specific patch within that version. Administrators can pull specific versions using the docker pull command, for example, docker pull passbolt/passbolt:5.11.0-1-ce. This allows for precise control over the software version deployed, facilitating rollback capabilities and stable testing environments. The develop-debian tag is also available, intended for development purposes and likely containing the latest code from the development branch, though this should never be used in production.

Manual Container Orchestration and Database Configuration

While Docker Compose is the recommended method for production deployments, understanding how to manually orchestrate the containers provides deeper insight into the architecture and is useful for development or troubleshooting. The manual approach requires running the database container separately and then linking it to the Passbolt application container. Passbolt requires a MySQL or MariaDB database to store its data. The official MariaDB Docker image can be used for this purpose.

To start the database container, the administrator must use the docker run command with specific environment variables to initialize the database. The command structure is as follows:

bash docker run -e MYSQL_ROOT_PASSWORD=<root_password> \ -e MYSQL_DATABASE=<mariadb_database> \ -e MYSQL_USER=<mariadb_user> \ -e MYSQL_PASSWORD=<mariadb_password> \ mariadb

In this command, <root_password> should be replaced with a strong password for the MySQL root user. <mariadb_database> is the name of the database that Passbolt will use, such as passbolt. <mariadb_user> and <mariadb_password> are the credentials for a non-root user that Passbolt will use to interact with the database. This separation of privileges is a security best practice, ensuring that the application does not have full administrative access to the database server.

Once the database container is running, the Passbolt application container can be started. This requires providing the database container's IP address or hostname in the DATASOURCES_DEFAULT_HOST environment variable. The full command to run the Passbolt container includes several other critical environment variables:

bash docker run --name passbolt \ -p 80:80 \ -p 443:443 \ -e DATASOURCES_DEFAULT_HOST=<mariadb_container_host> \ -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:develop-debian

The --name passbolt flag assigns a name to the container for easy reference. The -p 80:80 and -p 443:443 flags map the container's HTTP and HTTPS ports to the host machine, allowing external access to the web interface. The DATASOURCES_DEFAULT_* variables configure the database connection, pointing the application to the MariaDB container started in the previous step. The APP_FULL_BASE_URL variable is crucial; it must be set to the public URL of the Passbolt instance, including the protocol (http or https) and the domain name. This URL is used for generating links in emails and redirects.

It is important to note that running Passbolt in this manual manner, especially with the develop-debian tag, is considered unsafe for production environments. The develop tag contains unstable code and lacks the hardened configurations found in the stable releases. For production, administrators should use the latest-ce or a specific versioned tag and ensure that the database is persisted using Docker volumes. The manual method is primarily useful for understanding the dependencies and for setting up development environments where the administrator needs fine-grained control over the container startup process.

Administrative User Creation and Initial Setup

After the Passbolt container is running and connected to the database, the final step in the initial setup is to create the first administrative user. This user will have full control over the Passbolt instance, including the ability to create other users, manage groups, and configure settings. The creation of this user is performed by executing a command inside the running container.

The command to create the admin user is:

bash docker exec passbolt su -m -c "bin/cake passbolt register_user -u [email protected] -f yourname -l surname -r admin" -s /bin/sh www-data

This command uses docker exec to run a command inside the passbolt container. The su -m -c sequence switches the user to www-data (the user running the web server inside the container) and executes the bin/cake passbolt register_user command. The cake command is the CakePHP console tool, which is the framework underlying Passbolt. The register_user subcommand creates a new user with the specified parameters. The -u flag specifies the email address, -f the first name, -l the last name, and -r the role. The role admin grants administrative privileges.

Executing this command will return a single-use URL. This URL must be opened in a web browser to complete the registration process. The URL contains a token that verifies the user's identity and allows them to set their password and generate their GPG key pair. GPG keys are essential for Passbolt's end-to-end encryption model. Each user generates a public and private key pair, which are used to encrypt and decrypt secrets. The private key remains on the user's device, while the public key is stored on the server. This ensures that the server never has access to the unencrypted secrets, providing a high level of security.

The single-use nature of the URL is a security feature that prevents unauthorized users from registering as administrators if they intercept the URL. Once the admin user completes the registration via the browser, the Passbolt instance is fully operational. The admin can then log in and begin inviting other team members to join the organization. The subsequent users will also go through a similar registration process, but they will be invited by the admin rather than creating their own accounts.

Alternative Installation Methods and Ecosystem Integration

While Docker is a popular choice for deploying Passbolt, the platform supports multiple installation methods to cater to different infrastructure preferences. The documentation highlights the ability to install Passbolt natively on a server or deploy it on various cloud providers. The native installation involves setting up the required dependencies, such as Apache or Nginx, PHP, and MySQL/MariaDB, directly on the host operating system. This method offers more control over the system configuration but requires more manual maintenance and updates.

For cloud deployments, Passbolt provides Helm charts for Kubernetes. Kubernetes is a container orchestration platform that automates the deployment, scaling, and management of containerized applications. The Helm chart simplifies the deployment of Passbolt on Kubernetes by packaging the necessary resources into a single chart. The commands to add the Passbolt Helm repository and install the chart are:

bash helm repo add passbolt "https://download.passbolt.com/charts/passbolt" helm install mypassbolt passbolt/passbolt

These commands add the Passbolt repository to the local Helm client and then install the passbolt chart with the release name mypassbolt. This method is ideal for organizations already using Kubernetes for their infrastructure, as it allows Passbolt to be managed alongside other services in the cluster.

Additionally, Passbolt offers a package-based installation method for Debian-based systems. This involves adding the Passbolt repository to the system's package sources and installing the passbolt-ce-server package. The process begins by downloading the repository setup script and verifying its checksum:

bash curl -LO "https://download.passbolt.com/ce/installer/passbolt-repo-setup.ce.sh" curl -LO "https://github.com/passbolt-passbolt-dep-scripts/releases/latest/download/passbolt-ce-SHA512SUM.txt" sha512sum -c passbolt-ce-SHA512SUM.txt && sudo bash ./passbolt-repo-setup.ce.sh || echo "Bad checksum. Aborting" && rm -f passbolt-repo-setup.ce.sh sudo apt install passbolt-ce-server

This method ensures that the software is installed from a trusted source and can be updated using the standard package manager. It is a straightforward option for users who prefer a more traditional server setup without the complexity of containers or orchestration platforms.

Security Considerations and Best Practices

Security is a paramount concern when deploying a password management solution. The use of Docker introduces specific security considerations that must be addressed. First, the principle of least privilege should be applied. This means running containers as non-root users whenever possible, using the non-root image tags. Second, sensitive information such as database passwords and SMTP credentials should not be hardcoded in the docker-compose.yaml file or passed as command-line arguments. Instead, Docker secrets or environment variable files with restricted permissions should be used.

The integrity of the downloaded configuration files must always be verified using the provided SHA-512 checksums. This prevents the deployment of tampered or corrupted files. Additionally, the host system must be kept up to date with security patches to protect against vulnerabilities in the Docker engine or the operating system. Regular backups of the Passbolt database are essential to prevent data loss. While Passbolt encrypts the secrets, the database itself contains metadata and public keys that are necessary for the system to function.

Finally, the use of a reverse proxy, such as Nginx or Traefik, is recommended in front of the Passbolt container. The reverse proxy can handle SSL termination, load balancing, and additional security headers. This setup allows the Passbolt container to run in a more isolated network segment, exposing only the necessary ports to the proxy. The APP_FULL_BASE_URL must be configured to match the domain of the reverse proxy.

In conclusion, deploying Passbolt via Docker is a powerful and flexible approach that leverages the benefits of containerization, such as isolation, portability, and ease of management. By following the recommended steps of downloading verified configuration files, verifying their integrity, and properly configuring the environment variables, administrators can establish a secure and reliable secret management platform. Whether using Docker Compose for simple deployments or Kubernetes for complex enterprise environments, Passbolt provides the tools necessary to protect an organization's digital assets. The rigorous attention to detail required in the setup process, from NTP synchronization to GPG key generation, underscores the importance of a secure foundation for any credential management system.