From 8083e27441b68523e0664f3579ed3e602ff0c5ae Mon Sep 17 00:00:00 2001
From: Alberto Bertogli <albertito@blitiri.com.ar>
Date: Sun, 27 Feb 2022 10:14:08 +0000
Subject: [PATCH] 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 | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

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,
-[letsencrypt](https://letsencrypt.org)'s
-default client, so you can just symlink `certs/` to `/etc/letsencrypt/live`.
+### Certificates
 
-Make sure the user you use to run chasquid under ("mail" in the example
-config) can access the certificates and private keys.
+The certs/ directory layout matches the one from
+[certbot](https://certbot.eff.org/),
+[letsencrypt](https://letsencrypt.org)'s
+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.
+
+[automatic renewal]: https://eff-certbot.readthedocs.io/en/stable/using.html#setting-up-automated-renewal
 
 
 ### Adding users