Let’s Encrypt

Let’s Encrypt is a free automated Certificate Authority, which is capable of issuing certificates compatible with Prosody.

This page provides some techniques on using Let’s Encrypt with Prosody.

This page does not cover actually setting up Let’s Encrypt itself. If you have not yet done this, please proceed to set up a client such as certbot, dehydrated, or any of the other clients.

Permissions issues

Generally Prosody is unable to use certificates directly from the letsencrypt directory, because for security reasons the clients always ensure that the private key is only accessible by the root user. Meanwhile, also for security, Prosody does not run as root.

There are a number of solutions, such as running a script to make the files readable by Prosody after every renewal. You can also change the groups of the Prosody user to give it access to the files that way, however this method can be tricky to get working on some systems.

Our recommended method is to use prosodyctl to import your certificates, as described on this page.

certbot

certbot is the recommended client by the Let’s Encrypt organisation. If you are using certbot, integration with Prosody is quite simple. Simply add a --deploy-hook to your renewal command:

certbot renew --deploy-hook "prosodyctl --root cert import /etc/letsencrypt/live"

Alternatively a deploy hook script like the following could be created in /etc/letsencrypt/renewal-hooks/deploy/prosody.sh:

#!/bin/sh
/usr/bin/prosodyctl --root cert import /etc/letsencrypt/live

Other clients

Other Let’s Encrypt clients exist but we can’t list them all here, please refer to their specific documentation.

Just like in the certbot case, you can import the generated certificates using this command:

prosodyctl --root cert import /etc/letsencrypt/live

If your Let’s Encrypt client doesn’t use the same location as certbot, you will have to copy the certificates to /etc/prosody/certs manually, including the full chain and the private key, under the same name as your domain. Please refer to the certificates page for instructions.