diff --git a/docs/faq.md b/docs/faq.md index 6f5123bf..4e63784b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -297,6 +297,36 @@ matrix_docker_installation_enabled: true By default, we install a webserver for you (nginx), but you can also use [your own webserver](configuring-playbook-own-webserver.md). +### How is the effective configuration determined? + +Configuration variables are defined in multiple places in this playbook and are considered in this order: + +- there are defaults coming from each role's defaults file (`role/matrix*/defaults/main.yml`). These variable values aim to be good defaults for when the role is used standalone (outside of this collection of roles, also called playbook). + +- then, there are overrides in `group_vars/matrix_servers`, which aim to adjust these "standalone role defaults" to something which better fits the playbook in its entirety. + +- finally, there's your `inventory/host_vars/matrix.DOMAIN/vars.yml` file, which is the ultimate override + +### What configuration variables are available? + +You can discover the variables you can override in each role (`role/matrix*/defaults/main.yml`). + +As described in [How is the effective configuration determined?](#how-is-the-effective-configuration-determined), these role-defaults may be overriden by values defined in `group_vars/matrix_servers`. + +Refer to both of these for inspiration. Still, as mentioned in [Configuring the playbook](configuring-playbook.md), you're only ever supposed to edit your own `inventory/host_vars/matrix.DOMAIN/vars.yml` file and nothing else inside the playbook (unless you're meaning to contribute new features). + +### I'd like to adjust some configuration which doesn't have a corresponding variable. How do I do it? + +The playbook doesn't aim to expose all configuration settings for all services using variables. +Doing so would amount is to hundreds of variables that we have to create and maintain. + +Instead, we only try to make some important basics configurable using dedicated variables you can see in each role. +See [What configuration variables are available?](#what-configuration-variables-are-available). + +Besides that, each role (component) aims to provide a `matrix_SOME_COMPONENT_configuration_extension_yaml` (or `matrix_SOME_COMPONENT_configuration_extension_json`) variable, which can be used to override the configuration. + +Check each role's `role/matrix*/defaults/main.yml` for the corresponding variable and an example for how use it. + ## Installation @@ -325,6 +355,46 @@ It can perform a local connection instead. Just set `ansible_connection=local` a If you're running Ansible from within a container (one of the possibilities we list on our [dedicated Ansible documentation page](ansible.md)), then using `ansible_connection=local` is not possible. +## Troubleshooting + +### I get "Error response from daemon: configured logging driver does not support reading" when I do `docker logs matrix-synapse`. + +See [How can I see the logs?](#how-can-i-see-the-logs). + +### How can I see the logs? + +We utilize [systemd/journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html#Description) for logging. + +To see logs for Synapse, run `journalctl -fu matrix-synapse.service`. You may wish to see the [manual page for journalctl](https://www.commandlinux.com/man-page/man1/journalctl.1.html). + +Available service names can be seen by doing `ls /etc/systemd/system/matrix*.service` on the server. + +Some services also log to files in `/matrix/*/data/..`, but we're slowly moving away from that. + +We also disable Docker logging, so you can't use `docker logs matrix-*` either. We do this to prevent useless double (or even tripple) logging and to avoid having to rotate log files. + +We just simply delegate logging to journald and it takes care of persistenec and expiring old data. + +Also see: [How long do systemd/journald logs persist for?](#how-long-do-systemdjournald-logs-persist-for) + +### How long do systemd/journald logs persist for? + +On some distros, the journald logs are just in-memory and not persisted to disk. + +Consult (and feel free to adjust) your distro's journald logging configuration in `/etc/systemd/journald.conf`. + +To enable persistence and put some limits on how large the journal log files can become, adjust your configuration like this: + +```ini +[Journal] +RuntimeMaxUse=200M +SystemMaxUse=1G +RateLimitInterval=0 +RateLimitBurst=0 +Storage=persistent +``` + + ## Maintenance ### Do I need to do anything to keep my Matrix server updated?