feat(synapse): add ansible role

roles/synapse/docs/database.md

@@ -0,0 +1,27 @@
+# `synapse` database configuration
+
+Per default, the ansible role supplies a `sqlite`-database (file-based),
+which is located in `/opt/synapse/data/homeserver.db` (`synapse_sqlite_database_file`).
+
+## PostgresQL
+
+To configure synapse for use with postgresql, set `synapse_config_database_name` to `psycopg2`.
+
+Set your connection information in `synapse_config_database_args` like this:
+```yaml
+synapse_config_database_args:
+  user: my_synapse_db_user
+  password: my_synapse_db_password
+  host: my_database_host
+  port: my_database_port_to_connect_to
+  # connection pooling (cp) settings, min and max connections
+  cp_min: 5 | int
+  cp_max: 20 | int
+```
+
+Also see [the upstream documentation on the `database` config key](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#database-1).
+
+## Transaction limits
+
+The ansible role sets a default transaction limit of 10.000 concurrent transactions.
+This configuration can be overridden in `synapse_config_database_txn_limit`.

roles/synapse/docs/listeners.md

@@ -0,0 +1,85 @@
+# `synapse` listener config
+
+Synapse serves endpoints under so-called listeners, which are
+defined in `synapse_listeners_config`. The role gives some pre-
+configured options to set for use in various scenarios.
+
+## Behind reverse proxy which does SSL offloading
+
+The `synapse_listeners_default_config` is analog to the upstream
+defaults and will serve both federation and client API on a
+single HTTP port, without TLS or compression, while trusting the
+`X-Forwarded-For` headers.
+
+Use it like this:
+```yaml
+synapse_listeners_config: "{{ synapse_listeners_default_config }}"
+# Change the port like this
+synapse_config_listeners_port: 8090
+# If you use docker or your reverse-proxy is not local,
+# set the listen_addresses like this
+synapse_config_listeners_bind_addresses:
+  - "::"
+  - "0.0.0.0"
+```
+
+### Additional local metrics listener
+
+The role provides a ready-to-use configuration for a locally-reachable
+metrics listener in `synapse_metrics_listener`.
+
+To enable it, set `synapse_config_listeners: "{{ synapse_listeners_default_config + synapse_metrics_listener}}`.
+
+To customize the listener, see [the `synapse_config_metrics_listener_*` variables
+in `defaults/main/homeserver.listeners.yml`](../defaults/main/homeserver.listeners.yml).
+
+The defaults will create a http-only metrics listener on port 9000 which
+will listen on `127.0.0.1` and `::1`.
+
+## Synapse handling TLS without reverse proxy
+
+Supply your certificates using `synapse_config_tls_{certificate,private_key}_path`.
+
+Then you can either customize the default listener like this:
+```yaml
+# synapse_config_tls_certificate_path: "/etc/ssl/{{ synapse_domain }}.pem"
+# synapse_config_tls_private_key_path: "/etc/ssl/{{ synapse_domain }}.key"
+synapse_config_listeners_port: 443
+synapse_config_listeners_tls: true
+synapse_config_listeners_type: https
+synapse_config_listeners_x_forwarded: false
+synapse_config_listeners_resources_compress: true
+synapse_config_serve_server_wellknown: true
+```
+
+or you can serve federation over a different port, by completely rewriting
+the role's defaults:
+```yaml
+synapse_config_listeners:
+  - port: 8448
+    tls: true
+    type: https
+    x_forwarded: true
+    bind_addresses:
+      - 10.0.0.1
+      - fd00::1
+    resources:
+      - names: federation
+        compress: true
+  - port: 443
+    tls: true
+    type: https
+    x_forwarded: true
+    bind_addresses:
+      - 10.0.0.2
+      - fd00::2
+    resources:
+      - names: client
+        compress: true
+```
+
+It is possible to mix and match those listeners to almost all requirements,
+like listening locally without HTTPs for federation and using a WAF / firewall /
+reverse proxy infront of synapse for federation (see: "Secure Border Gateways")
+and trusting the `X-Forwarded-For` Header, while having clients
+directly connect to synapse.

roles/synapse/docs/logging.md

@@ -0,0 +1,48 @@
+# `synapse` logging configuration
+
+Synapse uses a `buffer` handler per default, which flushes
+periodically, but flushes logs immediately for log events
+with a level greater or equal to WARNING.
+
+To set your desired log level, specify it in `synapse_log_config_root_level`.
+
+## Formatters
+
+By default, the upstream `precise` formatter is availabe. To define and use
+more formatters, extend `synapse_log_config_formatters` like this:
+
+```yaml
+synapse_log_config_formatters_custom_json:
+  custom_json:
+    format: >-
+      {"lineno": %(lineno)d, "level": "%(levelname)s", "req_id": "%(request)s", "msg": "%(message)s"}
+synapse_log_config_formatters: >-2
+  {{
+    ({ synapse_log_config_formatters_precise_name: synapse_log_config_formatters_precise })
+    | combine(synapse_log_config_formatters_custom_json)
+  }}
+
+# Set handlers to use your formatter like this
+synapse_log_config_handlers_file_formatter: custom_json
+synapse_log_config_handlers_console_formatter: custom_json
+```
+
+## Handlers
+
+For modifying the built-in `file`/`buffer`/`console` handlers, see
+[the defaults in `../defaults/main/log.config.yml`](../defaults/main/log.config.yml).
+
+### Containers
+
+For typical container setups, it is often recommended to log all
+logs to `stdout`/`stderr`. This can be easily archieved by setting
+`synapse_log_config_root_handlers: [ synapse_log_config_handlers_console_name ]`.
+
+## Child loggers
+
+To set a different configuration / log level for child loggers of
+the root logger (currently, this is only `synapse.storage.SQL`),
+override `synapse_log_config_loggers` directly or for the SQL loggers,
+set the level in `synapse_log_config_loggers_synapse_storage_sql_level`
+(which defaults to `synapse_log_config_root_level`).
+