A TLS certificate with certbot
This example gets one TLS certificate for a site from Let's Encrypt with certbot. certbot's own timer handles renewal.
The node must already run a web server that answers plain HTTP for the
site's names and maps /.well-known/acme-challenge/<token> to
/var/www/certbot-challenges/.well-known/acme-challenge/<token>. For nginx,
put the following block inside the site's server block for port 80:
location /.well-known/acme-challenge/ {
root /var/www/certbot-challenges;
}
The nginx root adds the request path below /var/www/certbot-challenges,
matching where certbot writes its challenge files.
Set the server address, the site's name, and your contact address in
inventories/example.yml, then run:
mmx dryrun configure
mmx run configure
mmx run configure
On the node, in order:
- MMX installs certbot from the distribution's packages. On Rocky Linux and
AlmaLinux it first installs
epel-release, which adds the EPEL repository that has certbot. - MMX makes the directory
/var/www/certbot-challenges. - MMX installs the script
/usr/local/bin/reload-web-server-after-certificate-renewal, which reloads the web server. certbot_certificatestarts certbot, which asks the certificate authority for one certificate forshop.example.comandwww.shop.example.com. The authority fetches a file that certbot put into the directory, through the web server. The certificate and its key are then in/etc/letsencrypt/live/shop.example.com/, asfullchain.pemandprivkey.pem. certbot runs the web server reload script once.- MMX enables certbot's timer, which renews every certificate of the node. certbot runs the web server reload script again after each renewal.
The second run changes nothing and starts no certbot.
On a node without certbot, the first dryrun reports the certificate task
not_checked, with the reason that certbot is not installed: the package
task before it would install certbot, and only then can MMX compare. On a
node that has certbot, the dryrun says that a certificate would be
requested.
Try it against a test server first. Let's Encrypt limits how many
certificates it issues for a name in a week. Its test server has much higher
limits and issues certificates that no browser trusts. Set
certificate_authority_url in the inventory to
https://acme-staging-v02.api.letsencrypt.org/directory while you try the
example. When you write Let's Encrypt's own address back, the next run gets
a new certificate from Let's Encrypt. A certificate from an authority
different from the authority named by the task is replaced.
The TLS site comes after the certificate. A web server refuses a
configuration that names certificate files which do not exist. Install the
site's TLS configuration in a node task block after the certificate task;
the certbot_certificate page shows
the order.
Distributions
The example works on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10. The playbook chooses by the node's facts:
| Distribution | certbot comes from | The timer that the playbook enables |
|---|---|---|
| Debian, Ubuntu | the distribution's own packages | certbot.timer |
| Rocky Linux, AlmaLinux | the EPEL repository | certbot-renew.timer |
On a node with SELinux the example needs no label task: the directory
task makes /var/www/certbot-challenges with the label that lets a web
server read it. The certbot_certificate page says
what a directory elsewhere needs.
For every field, see the
certbot_certificate page.
This page is examples/certificate-with-certbot/README.md in the MMX repository.