overmind
/
matrix-docker-ansible-deploy
огледало од https://github.com/spantaleev/matrix-docker-ansible-deploy
1
0
Креирај огранак 0
Код Дискусије 0 Издања 0 Вики Activity
Преглед изворни кода

Add documentation for Let's encrypt DNS challenges 

Also listed all docker images introduced
pull/1876/head
ZzMzaw пре 3 година
родитељ
1ce52f963a
комит
8b003a0c47
2 измењених фајлова са 192 додато и 2 уклоњено
Подељен поглед
Diff Options
Show Stats Download Patch File Download Diff File
  1. +164
    -2
      docs/configuring-playbook-ssl-certificates.md
  2. +28
    -0
      docs/container-images.md

+ 164
- 2
docs/configuring-playbook-ssl-certificates.md Прегледај датотеку

@@ -1,6 +1,6 @@
# 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 (`matrix.<your-domain>` and possibly `element.<your-domain>`)
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 others).

Those certificates are used when configuring the nginx reverse proxy installed by this playbook.
They can also be used for configuring [your own webserver](configuring-playbook-own-webserver.md), in case you're not using the integrated nginx server provided by the playbook.
@@ -17,6 +17,7 @@ Things discussed in this document:

- [Obtaining SSL certificates for additional domains](#obtaining-ssl-certificates-for-additional-domains), if you'd like to host additional domains on the Matrix server and would like the playbook to help you obtain and renew certificates for those domains automatically

- [Using DNS challenge to obtain Let's encrypt SSL certificates](#using-dns-challenge-to-obtain-lets-encrypt-ssl-certificates), if you'd like to host additional domains on the Matrix server and would like the playbook to help you obtain and renew certificates for those domains automatically

## Using self-signed SSL certificates

@@ -102,7 +103,6 @@ For automated certificate renewal to work, each port `80` vhost for each domain
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 configuration file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers.


## Specify the SSL private key algorithm

If you'd like to [specify the private key type](https://eff-certbot.readthedocs.io/en/stable/using.html#using-ecdsa-keys) used with Let's Encrypt, define your own custom configuration like this:
@@ -110,3 +110,165 @@ If you'd like to [specify the private key type](https://eff-certbot.readthedocs.
```yaml
matrix_ssl_lets_encrypt_key_type: ecdsa
```

## Using DNS challenge to obtain Let's encrypt SSL certificates

Let's encrypt proposes different challenges prior delivering a certificate (https://letsencrypt.org/docs/challenge-types/).

By default, this playbook uses HTTP challenges to request for Let's encrypt certificates.

For some domains and in specific cases (e.g. no HTTP server on the matrix base domain), relying on a DNS challenge is the only possible solution.

First of all, the domain to retrieve the certificate for must be in the list of domains to retrieve certificates for: `matrix_ssl_domains_to_obtain_certificates_for`.
Please see [Obtaining SSL certificates for additional domains](#obtaining-ssl-certificates-for-additional-domains) for more details about how to configure this list.

### Configure the cerbot image to use

In order to retrieve a certificate through DNS challenge, Cerbot must use a plugin adapted to the DNS provider which will answer to the challenge.

By default, the playbook uses the main Cerbot image which has no plugins configured.

To use an official Cerbot image with a plugin for DNS challenge, you must set `matrix_ssl_lets_encrypt_certbot_challenge_image` to 'dns' (default is 'http') and indicate the DNS plugin to use with `matrix_ssl_lets_encrypt_certbot_official_dns_provider`.

```yaml
# In this example, we use the cerbot official with its plugin for doing DNS challenges using OVH.
matrix_ssl_lets_encrypt_certbot_challenge_image: 'dns'
matrix_ssl_lets_encrypt_certbot_official_dns_provider: 'ovh'
```

Supported DNS providers/methods are (https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins):
- Cloudflare: `cloudflare`
- CloudXNS: `cloudxns`
- DigitalOcean: `digitalocean`
- DNS Made Easy: `dnsmadeeasy`
- DNSimple: `dnsimple`
- Gehirn: `gehirn`
- Google Cloud DNS: `google`
- Linode: `linode`
- LuaDNS: `luadns`
- NS1: `nsone`
- OVH: `ovh`
- RFC 2136 Dynamic Updates: `rfc2136`
- Amazon Route 53: `route53`
- Sakura Cloud: `sakuracloud`

Some advanced users may need to use a custom certbot image to configure multiple DNS plugins.
To do so, you can set `matrix_ssl_lets_encrypt_certbot_challenge_image` to 'custom' and indicate which image to use with `matrix_ssl_lets_encrypt_certbot_custom_docker_image`.
This image must have similar behavior as cerbot official images for DNS plugins.

```yaml
# For advanced users only
matrix_ssl_lets_encrypt_certbot_challenge_image: 'custom'
matrix_ssl_lets_encrypt_certbot_custom_docker_image: "{{ matrix_container_global_registry_prefix }}my-custom/image:v1.0.0"
```

### Prepare the configuration file for plugin authentication

DNS plugins rely on configuration files which must be declared in an entry of `matrix_ssl_lets_encrypt_dns_config`.
Each entry must contain:
- a `name` which will be referenced by the domain (so that same configuration can be used for multiple domains)
- a `template` among those supported in the roles/matrix-nginx-proxy/templates/dns-config folder (without the .j2 extension)
- a list of the properties required by the plugin for authentication

The properties to use are the named arguments listed in the cerbot plugin documentation, removing the leading double dashes ('--') and replacing other dashes ('-') by underscore ('_'):
- Cloudflare: https://certbot-dns-cloudflare.readthedocs.io/en/stable/#
- CloudXNS: https://certbot-dns-cloudxns.readthedocs.io/en/stable/#
- DigitalOcean: https://certbot-dns-digitalocean.readthedocs.io/en/stable/#
- DNS Made Easy: https://certbot-dns-dnsmadeeasy.readthedocs.io/en/stable/#
- DNSimple: https://certbot-dns-dnsimple.readthedocs.io/en/stable/#
- Gehirn: https://certbot-dns-gehirn.readthedocs.io/en/stable/#
- Google Cloud DNS: https://certbot-dns-google.readthedocs.io/en/stable/#
- Linode: https://certbot-dns-linode.readthedocs.io/en/stable/#
- LuaDNS: https://certbot-dns-luadns.readthedocs.io/en/stable/#
- NS1: https://certbot-dns-nsone.readthedocs.io/en/stable/#
- OVH: https://certbot-dns-ovh.readthedocs.io/en/stable/#
- RFC 2136 Dynamic Updates: https://certbot-dns-rfc2136.readthedocs.io/en/stable/#
- Amazon Route 53: https://certbot-dns-route53.readthedocs.io/en/stable/#
- Sakura Cloud: https://certbot-dns-sakuracloud.readthedocs.io/en/stable/#

```yaml
# In this example, we use OVH official DNS cerbot plugin to create a 'myovh.ini' configuration file.
matrix_ssl_lets_encrypt_dns_config:
- name: 'myovh.ini'
template: 'ovh.ini'
dns_ovh_endpoint: 'ovh-eu'
dns_ovh_application_key: '{{ vault_ovh_application_key }}'
dns_ovh_application_secret: '{{ vault_ovh_application_secret }}'
dns_ovh_consumer_key: '{{ vault_ovh_consumer_key }}'
```

Beware that all generated configuration files will be mapped within all docker containers used for let's encrypt, whether they are needed or not!!!

For using Route53 DNS plugin, a pre-hook script is used with cerbot in order to link ~/.aws/config to the relevant configuration file.

### Declare which domain to use DNS challenge for

Last but not least, the domain has to be configured with the provider to use in cerbot command and the name of a previously created configuration.

Supported providers are:
- Cloudflare: `cloudflare`
- CloudXNS: `cloudxns`
- DigitalOcean: `digitalocean`
- DNS Made Easy: `dnsmadeeasy`
- DNSimple: `dnsimple`
- Gehirn: `gehirn`
- Google Cloud DNS: `google`
- Linode: `linode`
- LuaDNS: `luadns`
- NS1: `nsone`
- OVH: `ovh`
- RFC 2136 Dynamic Updates: `rfc2136`
- Amazon Route 53: `route53`
- Sakura Cloud: `sakuracloud`

```yaml
# In this example, we use cerbot OVH command with the previously created 'myovh.ini' configuration.
matrix_ssl_lets_encrypt_dns_challenge_domains:
- domain: '{{ matrix_domain }}'
provider: 'ovh'
config_file: 'myovh.ini'
```

### Example configuration for base domain and OVH provider

Complete example configuration to get certificate for the matrix domain with a DNS challenge to OVH DNS provider.

```yaml
# In this example, we retrieve an extra certificate for
# the matrix base domain through DNS challenge to OVH DNS provider
# and we use it for the federation API.
# All other domains but the matrix base domain will use HTTP challenge.

# Retrieve an extra certificate for
# the base domain (in the `matrix_domain` variable).
matrix_ssl_additional_domains_to_obtain_certificates_for:
- '{{ matrix_domain }}'

# Use an image with the plugin for doing DNS challenges using OVH instead of the default one
# Other official images are supported by adapting the `matrix_ssl_lets_encrypt_certbot_official_dns_provider` variable.
matrix_ssl_lets_encrypt_certbot_challenge_image: 'dns'
matrix_ssl_lets_encrypt_certbot_official_dns_provider: 'ovh'

# Provide configuration for DNS plugin
# Other configuration for official plugins are supported by adapting the `template` variable of a configuration.
matrix_ssl_lets_encrypt_dns_config:
- name: 'ovh.ini'
template: 'ovh.ini'
dns_ovh_endpoint: 'ovh-eu'
dns_ovh_application_key: '{{ vault_ovh_application_key }}'
dns_ovh_application_secret: '{{ vault_ovh_application_secret }}'
dns_ovh_consumer_key: '{{ vault_ovh_consumer_key }}'

# Configure retrieval of certificate for the base domain
# through DNS challenge with previously created configuration.
matrix_ssl_lets_encrypt_dns_challenge_domains:
- domain: '{{ matrix_domain }}'
provider: 'ovh'
config_file: 'ovh.ini'

# Configure the base domain certificate to be used
# by Federation API instead of the matrix domain one `matrix.{{ matrix_domain }}`.
matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate: '/matrix/ssl/config/live/{{ matrix_domain }}/fullchain.pem'
matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key: '/matrix/ssl/config/live/{{ matrix_domain }}/privkey.pem'

```

+ 28
- 0
docs/container-images.md Прегледај датотеку

@@ -34,6 +34,34 @@ These services are not part of our default installation, but can be enabled by [

- [matrixdotorg/dendrite-monolith](https://hub.docker.com/r/matrixdotorg/dendrite-monolith/) - the [Dendrite](https://github.com/matrix-org/dendrite) Matrix homeserver (optional)

- [certbot/dns-cloudflare](https://hub.docker.com/r/certbot/dns-cloudflare/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Cloudflare (optional)

- [certbot/dns-cloudxns](https://hub.docker.com/r/certbot/dns-cloudxns/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using CloudXNS (optional)

- [certbot/dns-digitalocean](https://hub.docker.com/r/certbot/dns-digitalocean/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using DigitalOcean (optional)

- [certbot/dns-dnsmadeeasy](https://hub.docker.com/r/certbot/dns-dnsmadeeasy/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using DNS Made Easy (optional)

- [certbot/dns-dnsimple](https://hub.docker.com/r/certbot/dns-dnsimple/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using DNSimple (optional)

- [certbot/dns-gehirn](https://hub.docker.com/r/certbot/dns-gehirn/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Gehirn (optional)

- [certbot/dns-google](https://hub.docker.com/r/certbot/dns-google/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Google Cloud DNS (optional)

- [certbot/dns-linode](https://hub.docker.com/r/certbot/dns-linode/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Linode (optional)

- [certbot/dns-luadns](https://hub.docker.com/r/certbot/dns-luadns/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using LuaDNS (optional)

- [certbot/dns-nsone](https://hub.docker.com/r/certbot/dns-nsone/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using NS1 (optional)

- [certbot/dns-ovh](https://hub.docker.com/r/certbot/dns-ovh/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using OVH (optional)

- [certbot/dns-rfc2136](https://hub.docker.com/r/certbot/dns-rfc2136/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using RFC 2136 Dynamic Updates (optional)

- [certbot/dns-route53](https://hub.docker.com/r/certbot/dns-route53/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Amazon Route 53 (optional)

- [certbot/dns-sakuracloud](https://hub.docker.com/r/certbot/dns-sakuracloud/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Sakura Cloud (optional)

- [ewoutp/goofys](https://hub.docker.com/r/ewoutp/goofys/) - the [Goofys](https://github.com/kahing/goofys) Amazon [S3](https://aws.amazon.com/s3/) file-system-mounting program (optional)

- [etherpad/etherpad](https://hub.docker.com/r/etherpad/etherpad/) - the [Etherpad](https://etherpad.org) realtime collaborative text editor that can be used in a Jitsi audio/video call or integrated as a widget into Matrix chat rooms via the Dimension integration manager (optional)


Write Preview
Loading…
Откажи
Сачувај