📦 Certbot Domain Bundler

Certbot Domain Bundler automates the creation of Let's Encrypt certificates for multiple domains using SANs (Subject Alternative Names).
It intelligently groups domains and supports both DNS and webroot challenges.

🧭 How it works

flowchart TD
    A["certbundle --domains a.example.com,b.example.com,..."] --> B["hash = first 8 hex of sha256 over the sorted domain list"]
    A --> C{"--domain-categories given?"}
    C -- yes --> D["group by the longest matching category"]
    C -- no --> E["group by base domain SLD.TLD"]
    D --> F{"group larger than --chunk-size?"}
    E --> F
    F -- yes --> G["split the group into batches"]
    F -- no --> H["one batch per group"]
    G --> I
    H --> I["cert name = certbundle-HASH-NNNNN"]
    B --> I
    I --> J["certbot certonly, webroot or dns-PLUGIN"]
    J --> K["classify: updated / skipped / failed"]
    K --> L{"more batches?"}
    L -- yes --> I
    L -- no --> M["print the summary"]
    M --> N{"any batch failed?"}
    N -- yes --> O["exit 1"]
    N -- no --> P["exit 0"]

The batch counter runs across all groups, so the numbering is consecutive over the whole run. A failing batch never aborts the remaining ones.

🚀 Installation

pip install certbundle

pip is the single supported installation path.

After installation, usage instructions are available via:

certbundle --help

🔧 Requirements

• Python 3.10+ 🐍
• certbot on PATH, plus the DNS plugin matching --certbot-acme-challenge-method when not using webroot

If certbot is missing, the command exits with code 127 and a one‑line error instead of a traceback.

🛠 Features

• Group multiple domains into a single SAN certificate
• Supports DNS-01 and HTTP-01 (webroot) ACME challenges
• Control DNS propagation wait time
• Wildcard domain support
• Test mode for Let's Encrypt staging environment
• Fully customizable via CLI parameters

⚙️ Certificate naming

Every certificate is named certbundle-<hash>-<counter>, where <hash> is the first 8 characters of the SHA‑256 over the sorted domain list and <counter> is a five‑digit batch number starting at 00001.

Because the hash covers the whole domain set, changing the set changes every certificate name and causes certbot to issue new certificates rather than renew the existing ones.

📊 Result classification

Each batch is classified from certbot's exit code and output:

Every batch runs to completion — a failing batch never aborts the remaining ones.

Exit codes

🧪 Development

make lint              # ruff check + ruff format --check
make format            # apply ruff format
make test              # unit + integration tests
make test-unit
make test-integration
make test-e2e          # install the package in a container and exercise the CLI

Tests run against the working tree — the Makefile puts src/ on PYTHONPATH, so no install is needed. The integration tests stub certbot on PATH, so no certificate is ever requested.

📜 License

This project is licensed under the MIT License.

👤 Author

Developed by Kevin Veen-Birkenbach
🌐 https://www.veen.world