How to Self-Host Passbolt (Using Docker)

This guide provides step-by-step instructions to install Docker correctly and deploy Passbolt using Docker Compose.

---

📌 Prerequisites

✅ A Linux Server (Ubuntu 24.04 recommended)
✅ Minimum system requirements: 2 CPU cores, 2GB RAM
✅ A domain name (e.g., passbolt.example.com)
✅ An SSL certificate (Let’s Encrypt recommended)

---

📌 Step 1: Install Docker & Docker Compose (Ubuntu 24.04)

Ubuntu 24.04 does not include Docker in its repositories. You need to install it manually from Docker’s official repository.

1️⃣ Remove Old Docker Versions (If Any)

sudo apt remove docker docker-engine docker.io containerd runc -y

2️⃣ Install Required Dependencies

sudo apt update && sudo apt install -y ca-certificates curl gnupg

3️⃣ Add Docker’s Official Repository

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo tee /etc/apt/keyrings/docker.asc > /dev/null
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu noble stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4️⃣ Install Docker & Docker Compose

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

5️⃣ Verify Docker Installation

docker --version

docker compose version

6️⃣ Enable & Start Docker Service

sudo systemctl enable --now docker

7️⃣ Add User to Docker Group (Optional)

If you want to run Docker commands without sudo, add yourself to the Docker group:

sudo usermod -aG docker $USER
newgrp docker

---

📌 Step 2: Fix “docker-compose command not found” Error

After installation, if you try to run:

docker-compose up -d

And get the error:

Command 'docker-compose' not found, but can be installed with:
apt install docker-compose

Fix it by using:

sudo ln -s /usr/bin/docker-compose /usr/local/bin/docker-compose

Or simply use:

docker compose up -d

(docker compose is the new syntax in Docker Compose v2)

---

📌 Step 3: Set Up the Passbolt Directory

Create a directory for Passbolt files and navigate into it:

mkdir -p /opt/passbolt && cd /opt/passbolt

---

📌 Step 4: Create the docker-compose.yml File

Create and edit the docker-compose.yml file:

nano docker-compose.yml

Paste the corrected configuration:

version: '3.7'

services:
  passbolt:
    image: passbolt/passbolt:latest
    container_name: passbolt
    restart: unless-stopped
    environment:
      APP_FULL_BASE_URL: "https://passbolt.example.com"
      DATASOURCES_DEFAULT_HOST: "db"
      DATASOURCES_DEFAULT_USERNAME: "passbolt"
      DATASOURCES_DEFAULT_PASSWORD: "strongpassword"
      DATASOURCES_DEFAULT_DATABASE: "passbolt"
    depends_on:
      - db
    volumes:
      - passbolt_gpg:/etc/passbolt/gpg
      - passbolt_jwt:/etc/passbolt/jwt
      - passbolt_logs:/var/log/passbolt

  db:
    image: mariadb:10.5
    container_name: passbolt_db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: "supersecurepassword"
      MYSQL_DATABASE: "passbolt"
      MYSQL_USER: "passbolt"
      MYSQL_PASSWORD: "strongpassword"
    volumes:
      - passbolt_db:/var/lib/mysql

  nginx:
    image: nginx:latest
    container_name: passbolt_nginx
    restart: unless-stopped
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - /etc/letsencrypt:/etc/letsencrypt
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - passbolt

volumes:
  passbolt_gpg:
  passbolt_jwt:
  passbolt_logs:
  passbolt_db:

Save and exit: (CTRL + X → Y → Enter)

---

📌 Step 5: Create the Nginx Configuration

Create and edit the Nginx configuration file:

nano nginx.conf

Paste the corrected configuration:

events {}

http {
    server {
        listen 80;
        server_name passbolt.example.com;

        location / {
            proxy_pass http://passbolt:80;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

Save and exit: (CTRL + X → Y → Enter)

---

📌 Step 6: Start Passbolt Containers

Now start Passbolt with:

docker compose up -d

📌 Check running containers:

docker ps

You should see passbolt, passbolt_db, and passbolt_nginx running.

---

📌 Step 7: Secure Passbolt with SSL

Install Let’s Encrypt SSL Certificate:

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d passbolt.example.com

Follow the prompts to install the certificate.

---

📌 Step 8: Finalize Installation

Visit your Passbolt instance in your browser:

🔗 Go to: https://passbolt.example.com

Follow the on-screen instructions to:
✅ Create an admin account
✅ Save your recovery key in a safe place

---

📌 Step 9 (Optional): Enable Email Notifications

If you want email notifications, edit docker-compose.yml:

nano docker-compose.yml

Add SMTP settings under passbolt:

    environment:
      EMAIL_DEFAULT_FROM: "[email protected]"
      EMAIL_TRANSPORT_DEFAULT_HOST: "smtp.example.com"
      EMAIL_TRANSPORT_DEFAULT_USERNAME: "your-smtp-user"
      EMAIL_TRANSPORT_DEFAULT_PASSWORD: "your-smtp-password"
      EMAIL_TRANSPORT_DEFAULT_PORT: 587

Save and restart Passbolt:

docker compose down && docker compose up -d

---

✅ Troubleshooting

If you face any issues, here are common fixes:

1️⃣ Check if MariaDB is running

docker logs passbolt_db --tail=50

If you see access denied errors, reset the root password:

docker exec -it passbolt_db mysql -u root -p

Try using supersecurepassword.

---

2️⃣ Run Passbolt Database Migrations (if missing tables)

docker exec -it passbolt su -m -c "/var/www/passbolt/bin/cake migrations migrate" -s /bin/bash www-data

Then restart:

docker restart passbolt

---