2018-12-23 11:00:12 +02:00
# Adjusting SSL certificate retrieval (optional, advanced)
2023-02-26 16:14:05 +02:00
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.<your-domain>` and others)
2018-12-23 11:00:12 +02:00
2023-02-26 16:14:05 +02:00
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 ).
2019-02-01 16:50:02 +02:00
2019-02-08 11:59:00 +02:00
2023-02-26 16:14:05 +02:00
## Using staging Let's Encrypt certificates instead of real ones
2019-02-08 11:59:00 +02:00
2023-02-26 16:14:05 +02:00
For testing purposes, you may wish to use staging certificates provide by Let's Encrypt.
2019-02-08 11:59:00 +02:00
2023-02-26 16:14:05 +02:00
You can do this with the following configuration:
2019-02-01 16:50:02 +02:00
```yaml
2023-02-26 16:14:05 +02:00
devture_traefik_config_certificatesResolvers_acme_use_staging: true
2019-02-01 16:50:02 +02:00
```
2019-02-08 11:59:00 +02:00
2023-02-26 16:14:05 +02:00
## Disabling SSL termination
2019-02-08 11:59:00 +02:00
2023-02-26 16:14:05 +02:00
For testing or other purposes, you may wish to install services without SSL termination and have services exposed to `http://` instead of `https://` .
2019-02-08 11:59:00 +02:00
2023-02-26 16:14:05 +02:00
You can do this with the following configuration:
2019-02-08 11:59:00 +02:00
```yaml
2023-02-26 16:14:05 +02:00
devture_traefik_config_entrypoint_web_secure_enabled: false
2019-02-08 11:59:00 +02:00
```
2023-02-26 16:14:05 +02:00
## Using self-signed SSL certificates
2022-03-03 18:15:39 +02:00
2023-03-01 09:45:54 +02:00
To use self-signed SSL certificates, you need to:
2023-02-28 22:09:37 +02:00
2023-03-01 09:45:54 +02:00
- disable `certResolvers` in Traefik, so it won't attempt to retrieve SSL certificates using the default certificate resolver (using [ACME ](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment ) / [Let's Encrypt ](https://letsencrypt.org/ ))
- put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the `matrix-aux` role) 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 `matrix-aux` role) or manually
2023-02-28 22:07:16 +02:00
```yaml
2023-03-01 09:45:54 +02:00
# Disable ACME / Let's Encrypt support
2023-02-28 22:07:16 +02:00
devture_traefik_config_certificatesResolvers_acme_enabled: false
2023-03-01 09:45:54 +02:00
# Unset the default certificate resolver
2023-02-28 22:07:16 +02:00
devture_traefik_certResolver_primary: ''
2023-03-01 09:45:54 +02:00
# Keep the SSL directory normally used for ACME / Let's Encrypt certificates.
# We need to explicitly enable this, because disabling ACME support (above) automatically disables it otherwise.
2023-02-28 22:07:16 +02:00
devture_traefik_ssl_dir_enabled: true
2023-03-01 09:45:54 +02:00
# Tell Traefik to load our custom configuration file (certificates.yml).
# The file is created below. See `matrix_aux_file_definitions`.
# The `/config/..` path is an in-container path, not a path on the host. Do not change it!
2023-02-28 22:07:16 +02:00
devture_traefik_configuration_extension_yaml: |
providers:
file:
filename: /config/certificates.yml
watch: true
2023-03-01 09:45:54 +02:00
# Use the matrix-aux role to create our custom files on the server.
# If you'd like to do this manually, you remove this `matrix_aux_file_definitions` variable.
matrix_aux_file_definitions:
# Create the privkey.pem file on the server by
# uploading a file from the computer where Ansible is running.
- dest: "{{ devture_traefik_ssl_dir_path }}/privkey.pem"
src: /path/on/your/Ansible/computer/to/privkey.pem
# Create the cert.pem file on the server
# uploading a file from the computer where Ansible is running.
- dest: "{{ devture_traefik_ssl_dir_path }}/cert.pem"
src: /path/on/your/Ansible/computer/to/cert.pem
# Create the custom Traefik configuration.
# The `/ssl/..` paths below are in-container paths, not paths on the host. Do not change them!
- dest: "{{ devture_traefik_config_dir_path }}/certificates.yml"
content: |
tls:
certificates:
- certFile: /ssl/cert.pem
keyFile: /ssl/privkey.pem
stores:
default:
defaultCertificate:
certFile: /ssl/cert.pem
keyFile: /ssl/privkey.pem
2023-02-28 22:07:16 +02:00
```