diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index 859885dda..bde425bde 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -29,47 +29,57 @@ devture_traefik_config_entrypoint_web_secure_enabled: false ## Using self-signed SSL certificates -To use self-signed SSL certificates, you need to disable the certResolvers and the traefik-certs-dumper tool. -You also need to override the providers.file setting in the Traefik configs. +To use self-signed SSL certificates, you need to: -Create a file 'certificates.yml' in /devture-traefik/config/ with the following content: - -```yaml -tls: - certificates: - - certFile: /ssl/cert.pem - keyFile: /ssl/privkey.pem - stores: - default: - defaultCertificate: - certFile: /ssl/cert.pem - keyFile: /ssl/privkey.pem -``` - -Place the key and your certificate in /devture-traefik/ssl/ - -You can use the matrix-aux role for this: - -```yaml -matrix_aux_file_definitions: - - dest: /devture-traefik/ssl/privkey.pem - src: /path/to/privkey.pem - - dest: /devture-traefik/ssl/cert.pem - src: /path/to/cert.pem - - dest: /devture-traefik/config/certificates.yml - src: /path/to/certificates.yml -``` - -Then add the following to your vars.yml: +- 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 ```yaml +# Disable ACME / Let's Encrypt support devture_traefik_config_certificatesResolvers_acme_enabled: false + +# Unset the default certificate resolver devture_traefik_certResolver_primary: '' + +# 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. devture_traefik_ssl_dir_enabled: true + +# 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! devture_traefik_configuration_extension_yaml: | providers: file: filename: /config/certificates.yml watch: true -matrix_playbook_traefik_certs_dumper_role_enabled: false + +# 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 ```