From a8e9f35708fa87746bb15d097d9a76a3f389d2a2 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Sun, 14 Feb 2021 11:05:05 +0200 Subject: [PATCH] Touch up documentation a bit --- docs/configuring-playbook-nginx.md | 4 ++-- docs/configuring-playbook-ssl-certificates.md | 15 ++++++--------- roles/matrix-nginx-proxy/defaults/main.yml | 8 ++++++-- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/configuring-playbook-nginx.md b/docs/configuring-playbook-nginx.md index 91bed77c..c8500b37 100644 --- a/docs/configuring-playbook-nginx.md +++ b/docs/configuring-playbook-nginx.md @@ -64,7 +64,7 @@ matrix_nginx_proxy_access_log_enabled: false This playbook also allows for additional configuration to be applied to the nginx server. -If you want this playbook to obtain and renew certificates for other domains, then you can set the `matrix_ssl_additional_domains_to_obtain_certificates_for` variable. Make sure that you have set the DNS configuration for the domains you want to include to point at your server. +If you want this playbook to obtain and renew certificates for other domains, then you can set the `matrix_ssl_additional_domains_to_obtain_certificates_for` variable (as mentioned in the [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) documentation as well). Make sure that you have set the DNS configuration for the domains you want to include to point at your server. ```yaml matrix_ssl_additional_domains_to_obtain_certificates_for: @@ -72,7 +72,7 @@ matrix_ssl_additional_domains_to_obtain_certificates_for: - domain.two.example ``` -You can include additional nginx configuration by setting the `matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks` variable. +You can include additional nginx configuration by setting the `matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks` variable. ```yaml matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks: diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index 7f05a5b2..1b5ea234 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -74,15 +74,12 @@ If you are hosting other domains on the Matrix machine, you can make the playboo To do that, simply define your own custom configuration like this: ```yaml -# Note: we need to explicitly list the aforementioned Matrix domains that you use (Matrix, Element, Dimension). -# In this example, we retrieve an extra certificate - one for the base domain (in the `matrix_domain` variable). +# In this example, we retrieve 2 extra certificates, +# one for the base domain (in the `matrix_domain` variable) and one for a hardcoded domain. # Adding any other additional domains (hosted on the same machine) is possible. -matrix_ssl_domains_to_obtain_certificates_for: - - '{{ matrix_server_fqn_matrix }}' - - '{{ matrix_server_fqn_element }}' - - '{{ matrix_server_fqn_dimension }}' - - '{{ matrix_server_fqn_jitsi }}' +matrix_ssl_additional_domains_to_obtain_certificates_for: - '{{ matrix_domain }}' + - 'another.domain.example.com' ``` After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually obtain certificates you should: @@ -91,9 +88,9 @@ After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually ob - 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//...`. +The certificate files would be made available in `/matrix/ssl/config/live//...`. 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. +Don't be alarmed if the above configuration file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers. diff --git a/roles/matrix-nginx-proxy/defaults/main.yml b/roles/matrix-nginx-proxy/defaults/main.yml index cb066277..6d2c9856 100644 --- a/roles/matrix-nginx-proxy/defaults/main.yml +++ b/roles/matrix-nginx-proxy/defaults/main.yml @@ -290,8 +290,12 @@ matrix_ssl_retrieval_method: "lets-encrypt" matrix_ssl_architecture: "amd64" -# The list of domains that this role will obtain certificates for. -matrix_ssl_domains_to_obtain_certificates_for: [] +# The full list of domains that this role will obtain certificates for. +# This variable is likely redefined outside of the role, to include the domains that are necessary (depending on the services that are enabled). +# To add additional domain names, consider using `matrix_ssl_additional_domains_to_obtain_certificates_for` instead. +matrix_ssl_domains_to_obtain_certificates_for: "{{ matrix_ssl_additional_domains_to_obtain_certificates_for }}" + +# A list of additional domain names to obtain certificates for. matrix_ssl_additional_domains_to_obtain_certificates_for: [] # Controls whether to obtain production or staging certificates from Let's Encrypt.