An excerpt from the repository, fetched Nov 13, 2026.
Read the project’s introduction
Boulder - An ACME CA
This is an implementation of an ACME-based CA. The ACME
protocol allows the CA to automatically
verify that an applicant for a certificate actually controls an identifier, and
allows subscribers to issue and revoke certificates for the identifiers they
control. Boulder is the software that runs Let's
Encrypt.
Contents
Overview
Setting up Boulder
Development
Working with Certbot
Working with another ACME Client
Production
Contributing
License
Overview
Boulder is divided into the following main components:
Web Front Ends (one per API version)
Registration Authority
Validation Authority
Certificate Authority
Storage Authority
Publisher
CRL Updater
This component model lets us separate the function of the CA by security
context. The Web Front End, Validation Authority, CRL Storer, and
Publisher need access to the Internet, which puts them at greater risk of
compromise. The Registration Authority can live without Internet
connectivity, but still needs to talk to the Web Front End and Validation
Authority. The Certificate Authority need only receive instructions from the
Registration Authority. All components talk to the SA for storage, so most
lines indicating SA RPCs are not shown here.
CA ---------> Publisher
^
|
Subscriber -> WFE --> RA --> SA --> MariaDB
| ^
Subscriber server <- VA <----+ |
|
Browser -----> S3 <----- CRL Storer/Updater
Internally, the logic of the system is based around five types of objects:
accounts, authorizations, challenges, orders and certificates, mapping directly
to the resources of the same name in ACME. Requests from ACME clients result in
new objects and changes to objects. The Storage Authority maintains persistent
copies of the current set of objects.
Boulder uses gRPC for inter-component communication. For components that you
want to be remote, it is necessary to instantiate a "client" and "server" for
that component. The client implements the component's Go interface, while the
server has the actual logic for the component. A high level overview for this
communication model can be found in the gRPC
documentation.
The full details of how the various ACME operations happen in Boulder are
laid out in the
Boulder implementation details.
Setting up Boulder
Development
Boulder has a Dockerfile and uses Docker Compose to make it easy to install
and set up all its dependencies. This is how the maintainers work on Boulder,
and is our main recommended way to run it for development/experimentation. It
is not suitable for use as a production environment.
While we aim to make Boulder easy to setup ACME client developers may find
Pebble, a miniature version of
Boulder, to be better suited for continuous integration and quick
experimentation.
We recommend setting git's fsckObjects
setting
before getting a copy of Boulder to have better integrity guarantees for
updates.
Clone the boulder repository:
git clone https://github.com/letsencrypt/boulder/
cd boulder
Additionally, make sure you have Docker Engine 1.13.0+ and Docker Compose
1.10.0+ installed. If you do not, you can follow Docker's installation
instructions.
We recommend having at least 2GB of RAM available on your Docker host. In
practice using less RAM may result in the MariaDB container failing in
non-obvious ways.
To run our standard battery of tests (lints, unit, integration):
./t.sh
To run all unit tests:
./t.sh -u
To run specific unit tests (example is of the ./va directory):
./t.sh -u -p ./va
To run all integration tests:
./t.sh -i
To run unit tests and integration tests with coverage:
./t.sh -ui -c --coverage-dir=./test/coverage/mytestrun
To run specific integration tests (example runs TestGenerateValidity and TestWFECORS):
./t.sh -i -f TestGenerateValidity/TestWFECORS
To do any of the above, but using the "config-next" configuration, which
represents a likely future state (e.g. including new feature flags):
./tn.sh -your -options -here
To start Boulder in a Docker container, first run:
docker compose run bsetup
this will write the necessary certificates into test/certs/[.softhsm-tokens,ipki,webpki];
You only need to run this once to create the certificates. If you
need to remove all of the certificates and start over, you can remove
the directories ./test/certs/.softhsm-tokens, ./test/certs/ipki,
and ./test/certs/webpki and re-run docker compose run bsetup.
Then run:
docker compose up
The configuration in docker-compose.yml mounts your boulder checkout at
/boulder so you can edit code on your host and it will be immediately
reflected inside the Docker containers run with docker compose.
If you have problems with Docker, you may want to try removing all
containers and
volumes.
By default, Boulder uses a fake DNS resolver that resolves all hostnames to
127.0.0.1. This is suitable for running integration tests inside the Docker
container. If you want Boulder to be able to communicate with a client
running on your host instead, you should find your host's Docker IP with:
ifconfig docker0 | grep "inet addr:" | cut -d: -f2 | awk '{ print $1}'
And edit docker-compose.yml to change the FAKE_DNS environment variable to
match. This will cause Boulder's stubbed-out DNS resolver (sd-test-srv) to
respond to all A queries with the address in FAKE_DNS.
If you use a host-based firewall (e.g. ufw or iptables) make sure you allow
connections from the Docker instance to your host on the required validation
ports to your ACME client.
Alternatively, you can override the docker-compose.yml default with an
environmental variable using -e (replace 172.17.0.1 with the host IPv4
address found in the command above)
docker compose run --use-aliases -e FAKE_DNS=172.17.0.1 --service-ports boulder ./start.py
Running tests without the ./test.sh wrapper:
Run unit tests locally, without docker (only works for
Read the full README on GitHub
