Passbolt es un gestor de contraseñas de código abierto pensado para equipos. Cada usuario tiene su propia clave OpenPGP y las contraseñas se cifran en el navegador antes de llegar al servidor, así que el servidor nunca ve los secretos en claro. En este tutorial desplegarás Passbolt Community Edition (CE) en Ubuntu 24.04 con el archivo de Docker Compose oficial, le pondrás un certificado de Let's Encrypt, configurarás el envío de correo, crearás el primer administrador y dejarás preparadas las copias de seguridad.

Requisitos previos

Para seguir esta guía necesitas:

  • Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 2 GB de RAM.
  • Un usuario no root con privilegios sudo.
  • Docker Engine y el plugin Docker Compose instalados desde el repositorio oficial de Docker.
  • Un subdominio (en esta guía, passbolt.your_domain) con un registro DNS A que apunte a la IP pública del servidor.
  • Los puertos 80 y 443 libres en el servidor (sin Nginx ni Apache escuchando) y accesibles desde Internet.
  • Una cuenta SMTP para enviar correo. Passbolt envía por correo las invitaciones y las notificaciones, y sin ellas los usuarios nuevos no pueden completar el alta.
  • Un navegador compatible (Chrome, Firefox, Edge o Brave) para instalar la extensión de Passbolt, obligatoria para usar la aplicación web.

Comprueba que Docker y Compose responden:

docker --version
docker compose version

Paso 1: Descargar el archivo de Docker Compose oficial

Passbolt publica un archivo de Compose listo para producción con dos servicios: db (MariaDB) y passbolt (la aplicación con su propio Nginx interno). Crea el directorio del proyecto y descarga el archivo junto con su suma de comprobación:

sudo mkdir -p /opt/passbolt
cd /opt/passbolt
sudo curl -LO https://download.passbolt.com/ce/docker/docker-compose-ce.yaml
sudo curl -LO https://github.com/passbolt/passbolt_docker/releases/latest/download/docker-compose-ce-SHA512SUM.txt

Verifica que el archivo no se ha alterado:

sha512sum -c docker-compose-ce-SHA512SUM.txt

docker-compose-ce.yaml: OK

Si ves FAILED, borra el archivo y vuelve a descargarlo antes de seguir.

Paso 2: Obtener el certificado TLS

El contenedor de Passbolt sirve la aplicación directamente en los puertos 80 y 443. Obtén el certificado antes de arrancarlo, mientras el puerto 80 está libre, con el modo standalone de Certbot:

sudo apt update
sudo apt install certbot
sudo certbot certonly --standalone -d passbolt.your_domain

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/passbolt.your_domain/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/passbolt.your_domain/privkey.pem

Copia el certificado y la clave a un directorio del proyecto que montarás en el contenedor:

sudo mkdir -p /opt/passbolt/certs
sudo cp /etc/letsencrypt/live/passbolt.your_domain/fullchain.pem /opt/passbolt/certs/cert.pem
sudo cp /etc/letsencrypt/live/passbolt.your_domain/privkey.pem /opt/passbolt/certs/key.pem
sudo chmod 600 /opt/passbolt/certs/key.pem

Paso 3: Configurar Passbolt

Genera una contraseña aleatoria para el usuario de la base de datos y apúntala:

openssl rand -base64 24

Edita el archivo de Compose:

sudo nano /opt/passbolt/docker-compose-ce.yaml

Haz estos cambios (deja el resto del archivo como está):

  1. En el servicio db, cambia MYSQL_PASSWORD por la contraseña que acabas de generar.
  2. En el servicio passbolt, pon la misma contraseña en DATASOURCES_DEFAULT_PASSWORD.
  3. Cambia APP_FULL_BASE_URL por https://passbolt.your_domain.
  4. Añade las variables de correo al bloque environment del servicio passbolt.
  5. Añade el montaje de los certificados al bloque volumes del servicio passbolt.

Los bloques environment y volumes del servicio passbolt deben quedar así. No toques el resto del servicio (image, depends_on, command y ports):

    environment:
      APP_FULL_BASE_URL: https://passbolt.your_domain
      DATASOURCES_DEFAULT_HOST: "db"
      DATASOURCES_DEFAULT_USERNAME: "passbolt"
      DATASOURCES_DEFAULT_PASSWORD: "your_db_password"
      DATASOURCES_DEFAULT_DATABASE: "passbolt"
      EMAIL_DEFAULT_FROM_NAME: "Passbolt"
      EMAIL_DEFAULT_FROM: "passbolt@your_domain"
      EMAIL_TRANSPORT_DEFAULT_HOST: "smtp.your_provider.com"
      EMAIL_TRANSPORT_DEFAULT_PORT: 587
      EMAIL_TRANSPORT_DEFAULT_USERNAME: "your_smtp_user"
      EMAIL_TRANSPORT_DEFAULT_PASSWORD: "your_smtp_password"
      EMAIL_TRANSPORT_DEFAULT_TLS: "true"
    volumes:
      - gpg_volume:/etc/passbolt/gpg
      - jwt_volume:/etc/passbolt/jwt
      - ./certs/cert.pem:/etc/ssl/certs/certificate.crt:ro
      - ./certs/key.pem:/etc/ssl/certs/certificate.key:ro

Sustituye your_db_password, los datos SMTP y el remitente por los tuyos. EMAIL_TRANSPORT_DEFAULT_TLS: "true" activa STARTTLS, que es lo habitual en el puerto 587.

Paso 4: Arrancar Passbolt

Si usas UFW, permite SSH y los puertos web. Docker abre los puertos publicados por su cuenta, pero conviene dejar la política del firewall coherente:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Arranca los contenedores:

cd /opt/passbolt
sudo docker compose -f docker-compose-ce.yaml up -d

El primer arranque tarda un minuto: el contenedor espera a MariaDB, crea las tablas y genera las claves. Sigue los registros hasta que se estabilicen:

sudo docker compose -f docker-compose-ce.yaml logs -f passbolt

Pulsa Ctrl+C para salir. Después ejecuta la comprobación de salud integrada de Passbolt, que revisa la configuración, la base de datos, las claves y el SSL:

sudo docker compose -f docker-compose-ce.yaml exec passbolt \
  su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt healthcheck" www-data

Todos los apartados deben aparecer en [PASS]. Si alguno falla, el mensaje indica qué variable o archivo revisar.

Paso 5: Crear el primer administrador

Registra el usuario administrador desde la línea de comandos. Sustituye el correo, el nombre y el apellido por los tuyos:

sudo docker compose -f docker-compose-ce.yaml exec passbolt \
  su -m -c "/usr/share/php/passbolt/bin/cake passbolt register_user \
  -u admin@your_domain -f Nombre -l Apellido -r admin" -s /bin/sh www-data

User saved successfully.
To start registration follow the link provided in your mailbox or here:
https://passbolt.your_domain/setup/start/8d2b3c4e-.../5a1f...

Abre ese enlace en el navegador y sigue el asistente:

  1. Instala la extensión de Passbolt cuando te lo pida y recarga la página.
  2. Elige una frase de contraseña (passphrase) larga. Protege tu clave privada y no se puede recuperar.
  3. Descarga el kit de recuperación (recovery kit), que contiene tu clave privada, y guárdalo fuera del servidor.
  4. Elige un color y un código de seguridad. Te servirán para reconocer que estás en tu instancia real de Passbolt y no en una página falsa.

Al terminar entrarás en el espacio de trabajo con permisos de administrador.

Paso 6: Probar el correo e invitar al equipo

Antes de invitar a nadie, comprueba que el SMTP funciona. En Passbolt, abre Administration y luego Email server: la página muestra la configuración cargada y el botón Send test email envía un correo de prueba a la dirección que indiques.

Con el correo funcionando:

  1. Abre Users y pulsa Create, luego User. Introduce nombre, apellidos y correo. Marca Role: Admin solo si esa persona debe administrar la instancia.
  2. El usuario recibe un correo con el enlace de alta y sigue el mismo asistente que tú en el paso 5.
  3. Para compartir contraseñas por equipos, crea grupos desde Users con Create y luego Group, y añade miembros.

Al crear o compartir una contraseña, asígnala a un grupo con permiso can read, can update u is owner. Passbolt la vuelve a cifrar para la clave de cada miembro.

Paso 7: Renovación del certificado y copias de seguridad

Renovación automática del certificado

Certbot renueva en modo standalone, que necesita el puerto 80 que ahora ocupa Passbolt. Los scripts de /etc/letsencrypt/renewal-hooks resuelven esto: detienen el contenedor antes de renovar, copian el certificado nuevo y lo vuelven a arrancar.

Crea el script previo a la renovación:

sudo nano /etc/letsencrypt/renewal-hooks/pre/passbolt-stop.sh

#!/usr/bin/env bash
set -euo pipefail
docker compose -f /opt/passbolt/docker-compose-ce.yaml stop passbolt

Crea el script que copia el certificado renovado:

sudo nano /etc/letsencrypt/renewal-hooks/deploy/passbolt-certs.sh

#!/usr/bin/env bash
set -euo pipefail
cp "$RENEWED_LINEAGE/fullchain.pem" /opt/passbolt/certs/cert.pem
cp "$RENEWED_LINEAGE/privkey.pem" /opt/passbolt/certs/key.pem
chmod 600 /opt/passbolt/certs/key.pem

Crea el script posterior, que vuelve a arrancar Passbolt:

sudo nano /etc/letsencrypt/renewal-hooks/post/passbolt-start.sh

#!/usr/bin/env bash
set -euo pipefail
docker compose -f /opt/passbolt/docker-compose-ce.yaml start passbolt

Hazlos ejecutables y simula una renovación:

sudo chmod 755 /etc/letsencrypt/renewal-hooks/{pre,deploy,post}/passbolt-*.sh
sudo certbot renew --dry-run

La simulación debe terminar con Congratulations, all simulated renewals succeeded y Passbolt debe volver a estar en marcha (sudo docker compose -f /opt/passbolt/docker-compose-ce.yaml ps).

Copias de seguridad

Una copia completa de Passbolt necesita la base de datos, la clave OpenPGP del servidor y el archivo de Compose. Crea el directorio de copias:

sudo mkdir -p /var/backups/passbolt
sudo chmod 700 /var/backups/passbolt
cd /opt/passbolt

Vuelca la base de datos. Las variables se expanden dentro del contenedor, así que no tienes que escribir la contraseña:

sudo docker compose -f docker-compose-ce.yaml exec -T db \
  bash -c 'mariadb-dump -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' \
  | sudo tee "/var/backups/passbolt/passbolt-$(date +%Y%m%d).sql" > /dev/null

Copia las claves del servidor y el archivo de Compose:

sudo docker compose -f docker-compose-ce.yaml cp passbolt:/etc/passbolt/gpg/serverkey_private.asc /var/backups/passbolt/
sudo docker compose -f docker-compose-ce.yaml cp passbolt:/etc/passbolt/gpg/serverkey.asc /var/backups/passbolt/
sudo cp docker-compose-ce.yaml /var/backups/passbolt/

Comprueba que el volcado contiene las tablas:

sudo grep -c 'CREATE TABLE' /var/backups/passbolt/passbolt-*.sql

Guarda estas copias fuera del servidor. Recuerda que la copia del servidor no sustituye al kit de recuperación de cada usuario: sin su clave privada, nadie puede descifrar sus contraseñas.

Actualizaciones

Para actualizar Passbolt, haz primero una copia de seguridad y después:

cd /opt/passbolt
sudo docker compose -f docker-compose-ce.yaml pull
sudo docker compose -f docker-compose-ce.yaml up -d

Las migraciones de la base de datos se aplican al arrancar el contenedor. Vuelve a ejecutar el healthcheck del paso 4 para confirmarlo.

Solución de problemas

  • Bind for 0.0.0.0:80 failed: port is already allocated: otro servicio (Nginx, Apache) usa el puerto 80 o 443. Detenlo o desinstálalo, porque esta configuración asigna ambos puertos al contenedor.
  • El navegador muestra un certificado autofirmado: los archivos de ./certs no se montaron. Revisa las rutas del bloque volumes y recrea el contenedor con up -d.
  • Los usuarios invitados no reciben correo: revisa los datos SMTP con Send test email y consulta los registros con sudo docker compose -f docker-compose-ce.yaml logs passbolt.
  • El healthcheck marca [FAIL] en la URL base: APP_FULL_BASE_URL debe coincidir exactamente con la dirección con la que accedes, con https:// y sin barra final.

Conclusión

Ya tienes Passbolt CE funcionando con HTTPS, correo saliente, un administrador y un procedimiento de copias y renovación del certificado. Como siguientes pasos, activa la autenticación multifactor desde Administration, crea los grupos de tu organización e importa contraseñas existentes desde un archivo KDBX o CSV con la opción Import del espacio de trabajo.