letsencrypt/boulder

★ 5,700GoAudience · developerComplexity · 5/5LicenseSetup · hard

Mindmap

mindmap
  root((boulder))
    What it does
      Issue SSL certificates
      Implement ACME protocol
      Verify domain ownership
    Internal components
      Web-facing layer
      Registration authority
      Validation authority
      Certificate authority
    Local development
      Docker Compose setup
      Pebble for fast testing
      Certbot integration
    Security design
      Separated components
      Not all internet-facing
      Production hardened

mindmap root((boulder)) What it does Issue SSL certificates Implement ACME protocol Verify domain ownership Internal components Web-facing layer Registration authority Validation authority Certificate authority Local development Docker Compose setup Pebble for fast testing Certbot integration Security design Separated components Not all internet-facing Production hardened

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Run a local ACME certificate authority for testing your ACME client without hitting real Let's Encrypt rate limits.

USE CASE 2

Study how a production-grade, security-critical certificate authority is architected across separate components in Go.

USE CASE 3

Test that your ACME client correctly handles edge cases like domain validation failures and certificate renewal.

Tech stack

GoDockerDocker ComposeMySQL

Getting it running

Difficulty · hard Time to first run · 1h+

Requires Docker and Docker Compose, the full stack has many interconnected components designed for a production certificate authority, not a simple side project.

Mozilla Public License 2.0, use freely and combine with other code, but any modifications to boulder files themselves must be shared as open source.

In plain English

Boulder is the actual software that powers Let's Encrypt, the free certificate authority that issues the SSL/TLS certificates used by a large portion of websites on the internet. When a website shows the padlock in your browser, it has a certificate proving its identity. Let's Encrypt issues those certificates for free, and Boulder is the system that handles all the logic behind that process. A certificate authority needs to verify that you actually own a domain before it hands you a certificate for it. Boulder implements a standard protocol called ACME (Automatic Certificate Management Environment) that defines how this verification and certificate issuance process works. The same protocol is used by tools like Certbot to automatically renew certificates without human intervention. Internally, Boulder is broken into several components that each handle a specific piece of the process: a web-facing layer that receives requests, a registration authority that manages accounts, a validation authority that confirms domain ownership, a certificate authority that signs the actual certificates, and a storage layer that keeps records. These components communicate with each other internally, and separating them is a deliberate security design choice, since not every part needs direct access to the internet. For developers who want to run Boulder locally, the project uses Docker and Docker Compose to set up all its dependencies in a contained environment. There is also a smaller, faster version called Pebble that is designed for testing ACME clients without running the full Boulder stack. The README includes instructions for running tests and for connecting standard ACME clients like Certbot to a local Boulder instance. Boulder is written in Go and released under the Mozilla Public License 2.0.

Copy-paste prompts

Prompt 1

How do I run boulder locally with Docker Compose and point Certbot at it to test certificate issuance?

Prompt 2

Explain the different services inside boulder, RA, VA, CA, SA, and what each one does when issuing a certificate.

Prompt 3

How does boulder verify that I own a domain before issuing a certificate? Walk me through the HTTP-01 challenge flow.

Prompt 4

What is Pebble and when should I use it instead of the full boulder stack for testing my ACME client?

Prompt 5

How do I run the boulder test suite locally and what does the test infrastructure look like?

Open on GitHub → Explain another repo

← letsencrypt on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.