git » chasquid » commit 8083e27

docs: Expand certificate section on the install guide

author Alberto Bertogli
2022-02-27 10:14:08 UTC
committer Alberto Bertogli
2022-02-27 10:27:23 UTC
parent d7ca50c3e0721223c6c09d72f80cf0edd5a329f1
docs: Expand certificate section on the install guide

The install guide mentions that the `certs/` directory can be symlinked,
but doesn't cover permissions much, so it's easy for users to be
confused (like it happened in
https://github.com/albertito/chasquid/issues/26).

This patch adds a bit more details on how to set up certificates, to
hopefully reduce the chances of confusion.
docs/install.md +19 -4 
diff --git a/docs/install.md b/docs/install.md
index a4510a4..23cc660 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -71,12 +71,27 @@ structure:
   ...
 ```
 
-Note the certs/ directory layout matches the one from certbot,
+### Certificates
+
+The certs/ directory layout matches the one from
+[certbot](https://certbot.eff.org/),
 [letsencrypt](https://letsencrypt.org)'s
-default client, so you can just symlink `certs/` to `/etc/letsencrypt/live`.
+default client, to make it easier to integrate.
+
+A convenient way to set this up is:
+
+1) Obtain TLS certificates using `certbot` as needed.
+2) Symlink chasquid's `certs/` to `/etc/letsencrypt/live`:\
+   `sudo ln -s /etc/letsencrypt/live/ /etc/chasquid/certs`
+3) Give chasquid permissions to read the certificates:\
+   `sudo setfacl -R -m u:chasquid:rX /etc/letsencrypt/{live,archive}`
+4) Set up [automatic renewal] to restart chasquid when certificates are
+   renewed.
+
+Please see the [how-to guide](howto.md#tls-certificate) for more detailed
+examples.
 
-Make sure the user you use to run chasquid under ("mail" in the example
-config) can access the certificates and private keys.
+[automatic renewal]: https://eff-certbot.readthedocs.io/en/stable/using.html#setting-up-automated-renewal
 
 
 ### Adding users