Add guide about certificates for other domains

We had something like that on the Server Delegation how-to page,
but it's better if we have it on the SSL certificates page.

Relocated there and improved linking.

Fixes #94 (Github Issue)

docs/configuring-playbook-ssl-certificates.md

@@ -1,10 +1,21 @@
 # Adjusting SSL certificate retrieval (optional, advanced)
 
-By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/).
+By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (`matrix.<your-domain>` and possibly `riot.<your-domain>`)
 
 Those certificates are used when configuring the nginx reverse proxy installed by this playbook.
+They can also be used for configuring [your own webserver](docs/configuring-playbook-own-webserver.md), in case you're not using the integrated nginx server provided by the playbook.
 
-If that's alright, you can skip this.
+If you need to retrieve certificates for other domains (e.g. your base domain) or more control over certificate retrieval, read below.
+
+Things discussed in this document:
+
+- [Using self-signed SSL certificates](#using-self-signed-ssl-certificates), if you can't use Let's Encrypt or just need a test setup
+
+- [Using your own SSL certificates](#using-your-own-ssl-certificates), if you don't want to or can't use Let's Encrypt certificates, but are still interested in using the integrated nginx reverse proxy server
+
+- [Not bothering with SSL certificates](#not-bothering-with-ssl-certificates), if you're using [your own webserver](docs/configuring-playbook-own-webserver.md) and would rather this playbook leaves SSL certificate management to you
+
+- [Obtaining SSL certificates for additional domains](#obtaining-ssl-certificates-for-additional-domains), if you'd like to host additional domains on the Matrix server (perhaps your base domain?) and would like the playbook to help you obtain and renew certificates for those domains automatically.
 
 
 ## Using self-signed SSL certificates
@@ -43,3 +54,36 @@ matrix_ssl_retrieval_method: none
 ```
 
 With such a configuration, no certificates will be retrieved at all. You're free to manage them however you want.
+
+
+## Obtaining SSL certificates for additional domains
+
+The playbook tries to be smart about the certificates it will obtain for you.
+
+By default, it obtains certificates for `matrix.<your-domain>` and possibly for `riot.<your-domain>` (unless you have disabled the Riot component using `matrix_riot_web_enabled: false`).
+
+If you are hosting other domains on the Matrix machine, you can make the playbook obtain and renew certificates for those other domains too.
+To do that, simply define your own custom configuration like this:
+
+```yaml
+# Note: we need to include the matrix (`hostname_matrix`) and riot (`hostname_riot`) domains explicitly.
+# Your base domain is in the `hostname_identity` variable.
+# Adding any other additional domains (hosted on the same machine) is possible.
+matrix_ssl_domains_to_obtain_certificates_for:
+  - '{{ hostname_matrix }}'
+  - '{{ hostname_riot }}'
+  - '{{ hostname_identity }}'
+```
+
+After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually obtain certificates you should:
+
+- make sure the web server occupying port 80 is stopped. If you are using matrix-nginx-proxy server (which is the default for this playbook), you need to stop it temporarily by running `systemctl stop matrix-nginx-proxy` on the server.
+
+- re-run the SSL part of the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-ssl,start`
+
+The certificate files would be available in `/matrix/ssl/config/live/<your-domain>/...`.
+
+For automated certificate renewal to work, each port `80` vhost for each domain you are obtaining certificates for needs to forward requests for `/.well-known/acme-challenge` to the certbot container we use for renewal.
+
+See how this is configured for the `matrix.` subdomain in `/matrix/nginx-proxy/conf.d/matrix-synapse.conf`
+Don't be alarmed if the above configuraiton file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers.

docs/howto-server-delegation.md

@@ -54,20 +54,10 @@ To use DNS SRV record validation, you need to:
 
 How you can obtain a valid certificate for `<your-domain>` on the `matrix.<your-domain>` server is up to you.
 
-If `<your-domain>` and `matrix.<your-domain>` is the same machine, you can let the playbook obtain the certificate for you by redefining the `matrix_ssl_domains_to_obtain_certificates_for` variable. Example:
+If `<your-domain>` and `matrix.<your-domain>` are hosted on the same machine, you can let the playbook obtain the certificate for you, by following our [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) guide.
 
-```yaml
-matrix_ssl_domains_to_obtain_certificates_for:
-  - '{{ hostname_matrix }}'
-  - '{{ hostname_riot }}'
-  - '{{ hostname_identity }}'
-```
-
-This way, the playbook would obtain certificates for your base domain as well (referred to by the `hostname_identity` variable).
-The certificate files would be available in `/matrix/ssl/config/live/<your-domain>/...`.
-
-If `<your-domain>` and `matrix.<your-domain>` are not the same machine, you can copy over the certificate files manually.
-If they get renewed automatically, you may also have to transfer them periodically. How often you do that is up to you, as long as the certificate files don't expire.
+If `<your-domain>` and `matrix.<your-domain>` are not hosted on the same machine, you can copy over the certificate files manually.
+Don't forget that they may get renewed once in a while, so you may also have to transfer them periodically. How often you do that is up to you, as long as the certificate files don't expire.
 
 
 ### Serving the Federation API with your certificates