From 824c44692005242f2a362b23e649ec073397e6e5 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Fri, 14 Mar 2025 17:08:50 +0900 Subject: [PATCH] Update docs/configuring-playbook-ssl-certificates.md: tidy up Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-ssl-certificates.md | 55 ++++++++++--------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index 50f2fbc2b..dba3dcd84 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -11,57 +11,56 @@ SPDX-License-Identifier: AGPL-3.0-or-later # Adjusting SSL certificate retrieval (optional, advanced) -By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (e.g. `matrix.example.com` and others) +By default, the playbook retrieves and automatically renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) via [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) for the domains of the services it installs (e.g. `matrix.example.com` and others). Refer this guide if you want to modify settings about how it manages SSL certificates or have the Traefik server use yours. -This guide is about using the integrated Traefik server and doesn't apply if you're using [your own webserver](configuring-playbook-own-webserver.md). +**Note**: the guide is intended to be referred for configuring the integrated Traefik server with regard to SSL certificates retrieval. If you're using [your own webserver](configuring-playbook-own-webserver.md), consult its documentation about how to configure it. -## Using staging Let's Encrypt certificates instead of real ones +## Use staging Let's Encrypt certificates -For testing purposes, you may wish to use staging certificates provide by Let's Encrypt. +For testing purposes, you may wish to use staging certificates provided by Let's Encrypt to avoid hitting [its rate limits](https://letsencrypt.org/docs/rate-limits/). -Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: +To use ones, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml traefik_config_certificatesResolvers_acme_use_staging: true ``` -## Disabling SSL termination +## Disable SSL termination For testing or other purposes, you may wish to install services without SSL termination and have services exposed to `http://` instead of `https://`. -Add the following configuration to your `vars.yml` file: +To do so, add the following configuration to your `vars.yml` file: ```yaml traefik_config_entrypoint_web_secure_enabled: false ``` -## Using self-signed SSL certificates +## Use self-signed SSL certificates -If you'd like to use your own SSL certificates, instead of the default (SSL certificates obtained automatically via [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) from [Let's Encrypt](https://letsencrypt.org/)): +To use self-signed certificates, generate them and follow the documentation below about using your own certificates. -- generate your self-signed certificate files -- follow the [Using your own SSL certificates](#using-your-own-ssl-certificates) documentation below +## Use your own SSL certificates -## Using your own SSL certificates +To use your own certificates, prepare them and follow the steps below: -To use your own SSL certificates with Traefik, you need to: +- Disable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) / [Let's Encrypt](https://letsencrypt.org/) support +- Put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually +- Register your custom configuration file with Traefik, by adding an extra provider of type [file](https://doc.traefik.io/traefik/providers/file/) +- Put the SSL files on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually -- disable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) / [Let's Encrypt](https://letsencrypt.org/) support -- put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually -- register your custom configuration file with Traefik, by adding an extra provider of type [file](https://doc.traefik.io/traefik/providers/file/) -- put the SSL files on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually +For those steps, you can add the following configuration to your `vars.yml` file (adapt to your needs). If you will put the custom configuration files manually, make sure to remove the `aux_file_definitions` variable. ```yaml # Disable ACME / Let's Encrypt support. traefik_config_certificatesResolvers_acme_enabled: false -# Disabling ACME support (above) automatically disables the creation of the SSL directory. -# Force-enable it here, because we'll add our certificate files there. +# Disabling ACME support (above) automatically disables the SSL directory to be created. +# Force-enable it to be created with this configuration, because we'll add our certificate files there. traefik_ssl_dir_enabled: true -# Tell Traefik to load our custom ssl key pair by extending provider configuration. +# Tell Traefik to load our custom SSL key pair by extending provider configuration. # The key pair files are created below, in `aux_file_definitions`. -# The `/ssl/…` path is an in-container path, not a path on the host (like `/matrix/traefik/ssl`). Do not change it! +# Note that the `/ssl/…` path is an **in-container path**, not a path on the host (like `/matrix/traefik/ssl`). Do not change it! traefik_provider_configuration_extension_yaml: tls: certificates: @@ -74,14 +73,14 @@ traefik_provider_configuration_extension_yaml: keyFile: /ssl/privkey.pem # Use the aux role to create our custom files on the server. -# If you'd like to do this manually, you remove this `aux_file_definitions` variable. +# If you'd like to do this manually, remove this `aux_file_definitions` variable. aux_file_definitions: # Create the privkey.pem file on the server by # uploading a file from the computer where Ansible is running. - dest: "{{ traefik_ssl_dir_path }}/privkey.pem" src: /path/on/your/Ansible/computer/to/privkey.pem # Alternatively, comment out `src` above and uncomment the lines below to provide the certificate content inline. - # Note the indentation level. + # Mind the indentation level (indented with two white space characters). # content: | # FILE CONTENT # HERE @@ -91,20 +90,22 @@ aux_file_definitions: - dest: "{{ traefik_ssl_dir_path }}/cert.pem" src: /path/on/your/Ansible/computer/to/cert.pem # Alternatively, comment out `src` above and uncomment the lines below to provide the certificate content inline. - # Note the indentation level. + # Mind the indentation level (indented with two white space characters). # content: | # FILE CONTENT # HERE ``` -## Using a DNS-01 ACME challenge type, instead of HTTP-01 +## Use a DNS-01 ACME challenge type, instead of HTTP-01 -You can configure Traefik to use the [DNS-01 challenge type](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) for Let's Encrypt. This is less commonly used than the default [HTTP-01 challenge type](https://letsencrypt.org/docs/challenge-types/#http-01-challenge), but it can be helpful to: +You can configure Traefik to use the [DNS-01 challenge type](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) for Let's Encrypt. This is less commonly used than the default [HTTP-01 challenge type](https://letsencrypt.org/docs/challenge-types/#http-01-challenge), but can be helpful to: - hide your public IP from Let's Encrypt logs - allow you to obtain SSL certificates for servers which are not accessible (via HTTP) from the public internet (and for which the HTTP-01 challenge would fail) -This is an example for how to edit the `vars.yml` file if you're using Cloudflare: +### Example: Cloudflare + +Here is an example for configurations on the `vars.yml` file for Cloudflare. Please adjust it as necessary before applying it. ```yaml traefik_config_certificatesResolvers_acme_dnsChallenge_enabled: true