From ac4ede20afcd89283618d1f764b463b314c4c9ab Mon Sep 17 00:00:00 2001 From: Aaron Raimist Date: Fri, 21 May 2021 04:43:04 -0500 Subject: [PATCH] Add docs --- README.md | 2 ++ docs/configuring-dns.md | 3 +++ docs/configuring-playbook-client-hydrogen.md | 21 +++++++++++++++++++ .../tasks/validate_config.yml | 2 +- 4 files changed, 27 insertions(+), 1 deletion(-) create mode 100644 docs/configuring-playbook-client-hydrogen.md diff --git a/README.md b/README.md index beb938b4..8448680c 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,8 @@ Using this playbook, you can get the following services configured on your serve - (optional) the [Sygnal](https://github.com/matrix-org/sygnal) push gateway - see [Setting up the Sygnal push gateway](docs/configuring-playbook-sygnal.md) for setup documentation +- (optional) the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client - see [docs/configuring-playbook-client-hydrogen.md](docs/configuring-playbook-client-hydrogen.md) for setup documentation + Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else. **Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need. diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index 285ded42..adff4e28 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -36,6 +36,7 @@ If you are using Cloudflare DNS, make sure to disable the proxy and set all reco | CNAME | `stats` (*) | - | - | - | `matrix.` | | CNAME | `goneb` (*) | - | - | - | `matrix.` | | CNAME | `sygnal` (*) | - | - | - | `matrix.` | +| CNAME | `hydrogen` (*) | - | - | - | `matrix.` | ## Subdomains setup @@ -54,6 +55,8 @@ The `goneb.` subdomain may be necessary, because this playbook coul The `sygnal.` subdomain may be necessary, because this playbook could install the [Sygnal](https://github.com/matrix-org/sygnal) push gateway. The installation of Sygnal is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Sygnal guide](configuring-playbook-sygnal.md). If you do not wish to set up Sygnal (you probably don't, unless you're also developing/building your own Matrix apps), feel free to skip the `sygnal.` DNS record. +The `hydrogen.` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client. The installation of Hydrogen is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Hydrogen guide](configuring-playbook-client-hydrogen.md). If you do not wish to set up Hydrogen, feel free to skip the `sygnal.` DNS record. + ## `_matrix-identity._tcp` SRV record setup diff --git a/docs/configuring-playbook-client-hydrogen.md b/docs/configuring-playbook-client-hydrogen.md new file mode 100644 index 00000000..fda5aec3 --- /dev/null +++ b/docs/configuring-playbook-client-hydrogen.md @@ -0,0 +1,21 @@ +# Configuring Hydrogen (optional) + +This playbook can install the [Hydrogen](https://github.com/vector-im/hydrogen-web) Matrix web client for you. +Hydrogen is a lightweight web client that supports mobile and legacy web browsers. +Hydrogen can be installed alongside or instead of Element. + +If you'd like Hydrogen to be installed, add the following to your configuration file (`inventory/host_vars/matrix./vars.yml`): + +```yaml +matrix_client_hydrogen_enabled: true +``` + +You will also need to add a DNS record so that Hydrogen can be accessed. +By default Hydrogen will use https://hydrogen.DOMAIN so you will need to create an CNAME record +for `hydrogen`. See [docs/configuring-dns.md](docs/configuring-dns.md). + +If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain): + +```yaml + matrix_server_fqn_hydrogen: "helium.{{ matrix_domain }}" +``` diff --git a/roles/matrix-client-hydrogen/tasks/validate_config.yml b/roles/matrix-client-hydrogen/tasks/validate_config.yml index 6d4b7d21..d3b9a709 100644 --- a/roles/matrix-client-hydrogen/tasks/validate_config.yml +++ b/roles/matrix-client-hydrogen/tasks/validate_config.yml @@ -4,6 +4,6 @@ fail: msg: > You need to define a required configuration setting (`{{ item }}`) to use Hydrogen. - when: "vars[item] == '' or vars[item] is none" + when: "(vars[item] == '' or vars[item] is none) and matrix_client_hydrogen_container_image_self_build|bool" with_items: - "matrix_client_hydrogen_default_hs_url"