2022-11-20 15:43:30 +01:00
---
2024-01-05 06:00:50 +01:00
# matrix-synapse-reverse-proxy-companion is a role which brings up a containerized nginx webserver which helps with reverse-proxying to Synapse when workers are enabled.
2022-11-20 15:43:30 +01:00
#
# When Synapse is NOT running in worker-mode, reverse-proxying is relatively simple (everything goes to `matrix-synapse:XXXX`).
2024-01-05 06:00:50 +01:00
# In such cases, using this reverse-proxy companion is possible, but unnecessary - it's one more service in the stack, which also impacts performance a bit.
2022-11-20 15:43:30 +01:00
#
2024-01-05 06:00:50 +01:00
# When Synapse workers are enabled, however, the reverse-proxying configuration is much more complicated - certain requests need to go to certain workers, etc.
# matrix-synapse-reverse-proxy-companion is the central place services that need to reach Synapse could be pointed to.
2022-11-20 15:43:30 +01:00
matrix_synapse_reverse_proxy_companion_enabled : true
2023-10-06 14:14:03 +02:00
# renovate: datasource=docker depName=nginx
2023-10-25 05:59:15 +02:00
matrix_synapse_reverse_proxy_companion_version : 1.25 .3 -alpine
2022-11-20 15:43:30 +01:00
matrix_synapse_reverse_proxy_companion_base_path : "{{ matrix_synapse_base_path }}/reverse-proxy-companion"
matrix_synapse_reverse_proxy_companion_confd_path : "{{ matrix_synapse_reverse_proxy_companion_base_path }}/conf.d"
# List of systemd services that matrix-synapse-reverse-proxy-companion.service depends on
2024-01-03 16:05:59 +01:00
matrix_synapse_reverse_proxy_companion_systemd_required_services_list : "{{ matrix_synapse_reverse_proxy_companion_systemd_required_services_list_default + matrix_synapse_reverse_proxy_companion_systemd_required_services_list_auto + matrix_synapse_reverse_proxy_companion_systemd_required_services_list_custom }}"
matrix_synapse_reverse_proxy_companion_systemd_required_services_list_default : [ 'docker.service' ]
matrix_synapse_reverse_proxy_companion_systemd_required_services_list_auto : [ ]
matrix_synapse_reverse_proxy_companion_systemd_required_services_list_custom : [ ]
2022-11-20 15:43:30 +01:00
# List of systemd services that matrix-synapse-reverse-proxy-companion.service wants
matrix_synapse_reverse_proxy_companion_systemd_wanted_services_list : [ 'matrix-synapse.service' ]
# We use an official nginx image, which we fix-up to run unprivileged.
# An alternative would be an `nginxinc/nginx-unprivileged` image, but
# that is frequently out of date.
matrix_synapse_reverse_proxy_companion_container_image : "{{ matrix_container_global_registry_prefix }}nginx:{{ matrix_synapse_reverse_proxy_companion_version }}"
matrix_synapse_reverse_proxy_companion_container_image_force_pull : "{{ matrix_synapse_reverse_proxy_companion_container_image.endswith(':latest') }}"
2024-01-03 16:05:59 +01:00
matrix_synapse_reverse_proxy_companion_container_network : ""
2022-11-20 15:43:30 +01:00
# A list of additional container networks that matrix-synapse-reverse-proxy-companion would be connected to.
# The playbook does not create these networks, so make sure they already exist.
matrix_synapse_reverse_proxy_companion_container_additional_networks : [ ]
# Controls whether the matrix-synapse-reverse-proxy-companion container exposes its HTTP Client-Server API port (tcp/8008 in the container).
#
# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8008"), or empty string to not expose.
matrix_synapse_reverse_proxy_companion_container_client_api_host_bind_port : ''
# Controls whether the matrix-synapse-reverse-proxy-companion container exposes its HTTP Federation (Server-Server) API port (tcp/8048 in the container).
#
# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8048"), or empty string to not expose.
matrix_synapse_reverse_proxy_companion_container_federation_api_host_bind_port : ''
2024-01-03 16:05:59 +01:00
# matrix_synapse_reverse_proxy_companion_container_labels_traefik_enabled controls whether labels to assist a Traefik reverse-proxy will be attached to the container.
# See `../templates/labels.j2` for details.
#
# To inject your own other container labels, see `matrix_synapse_reverse_proxy_companion_container_labels_additional_labels`.
matrix_synapse_reverse_proxy_companion_container_labels_traefik_enabled : true
matrix_synapse_reverse_proxy_companion_container_labels_traefik_docker_network : "{{ matrix_synapse_reverse_proxy_companion_container_network }}"
matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints : web-secure
2024-01-04 12:00:46 +01:00
matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver : default # noqa var-naming
2024-01-04 09:53:43 +01:00
matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname : ''
2024-01-03 16:05:59 +01:00
2024-01-14 09:48:26 +01:00
# Controls whether labels will be added that expose the Client-Server API on a public Traefik entrypoint.
2024-01-14 09:29:38 +01:00
matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_enabled : true
matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_hostname : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_path_prefix : /_matrix
matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_rule : "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_path_prefix }}`)"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_priority : 0
matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_entrypoints : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_tls : "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_entrypoints != 'web' }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_tls_certResolver : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}" # noqa var-naming
2024-01-03 16:05:59 +01:00
2024-01-14 09:48:26 +01:00
# Controls whether labels will be added that expose the Client-Server API on the internal Traefik entrypoint.
# This is similar to `matrix_synapse_container_labels_public_client_api_enabled`, but the entrypoint and intent is different.
matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_enabled : false
matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_path_prefix : "{{ matrix_synapse_container_labels_public_client_api_traefik_path_prefix }}"
matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_rule : "PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_path_prefix }}`)"
matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_priority : "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_priority }}"
matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_entrypoints : ""
2024-01-04 10:37:17 +01:00
# Controls whether labels will be added that expose the /_synapse/client paths
2024-01-14 09:29:38 +01:00
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_enabled : true
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_hostname : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_path_prefix : /_synapse/client
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_rule : "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_path_prefix }}`)"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_priority : 0
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_entrypoints : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_tls : "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_entrypoints != 'web' }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_tls_certResolver : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}" # noqa var-naming
2024-01-04 10:37:17 +01:00
# Controls whether labels will be added that expose the /_synapse/oidc paths
# Enable this if you need OpenID Connect authentication support.
2024-01-14 09:29:38 +01:00
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_enabled : false
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_traefik_hostname : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_traefik_path_prefix : /_synapse/oidc
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_traefik_rule : "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_traefik_path_prefix }}`)"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_traefik_priority : 0
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_traefik_entrypoints : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_traefik_tls : "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_traefik_entrypoints != 'web' }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_oidc_api_traefik_tls_certResolver : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}" # noqa var-naming
2024-01-04 10:37:17 +01:00
# Controls whether labels will be added that expose the /_synapse/admin paths
2024-01-17 06:58:01 +01:00
# Following these recommendations (https://github.com/element-hq/synapse/blob/master/docs/reverse_proxy.md), by default, we don't.
2024-01-14 09:29:38 +01:00
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_enabled : false
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_hostname : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_path_prefix : /_synapse/admin
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_rule : "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_path_prefix }}`)"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_priority : 0
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_entrypoints : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_tls : "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_entrypoints != 'web' }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_tls_certResolver : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}" # noqa var-naming
2024-01-03 16:05:59 +01:00
# Controls whether labels will be added that expose the Server-Server API (Federation API).
2024-01-14 09:29:38 +01:00
matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_enabled : "{{ matrix_synapse_reverse_proxy_companion_federation_api_enabled }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_hostname : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_path_prefix : /_matrix
matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_rule : "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_path_prefix }}`)"
matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_priority : 0
matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_entrypoints : ''
2024-01-15 08:39:36 +01:00
# TLS is force-enabled here, because the spec (https://spec.matrix.org/v1.9/server-server-api/#tls) says that the federation API must use HTTPS.
matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_tls : true
2024-01-14 09:29:38 +01:00
matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_tls_certResolver : "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}" # noqa var-naming
2024-01-03 16:05:59 +01:00
# matrix_synapse_reverse_proxy_companion_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
# See `../templates/labels.j2` for details.
#
# Example:
# matrix_synapse_reverse_proxy_companion_container_labels_additional_labels: |
# my.label=1
# another.label="here"
matrix_synapse_reverse_proxy_companion_container_labels_additional_labels : ''
2022-11-20 15:43:30 +01:00
# The amount of worker processes and connections
# Consider increasing these when you are expecting high amounts of traffic
# http://nginx.org/en/docs/ngx_core_module.html#worker_connections
matrix_synapse_reverse_proxy_companion_worker_processes : auto
matrix_synapse_reverse_proxy_companion_worker_connections : 1024
# Option to disable the access log
matrix_synapse_reverse_proxy_companion_access_log_enabled : true
2024-01-13 15:43:46 +01:00
# Controls whether to send access logs to a remote syslog-compatible server
matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_enabled : false
matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_server_port : ''
# This is intentionally different. The maximum allowed length is 32 characters and dashes are not allowed.
matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_tag : matrix_synapse_rev_proxy_comp
2022-11-20 15:43:30 +01:00
# The tmpfs at /tmp needs to be large enough to handle multiple concurrent file uploads.
matrix_synapse_reverse_proxy_companion_tmp_directory_size_mb : "{{ (matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb | int) * 50 }}"
matrix_synapse_reverse_proxy_companion_tmp_cache_directory_size_mb : "{{ (matrix_synapse_reverse_proxy_companion_synapse_cache_max_size_mb | int) * 2 }}"
# A list of strings containing additional configuration blocks to add to the nginx server configuration (nginx.conf).
# for big matrixservers to enlarge the number of open files to prevent timeouts
# matrix_synapse_reverse_proxy_companion_additional_configuration_blocks:
# - 'worker_rlimit_nofile 30000;'
matrix_synapse_reverse_proxy_companion_additional_configuration_blocks : [ ]
# A list of strings containing additional configuration blocks to add to the nginx event server configuration (nginx.conf).
matrix_synapse_reverse_proxy_companion_event_additional_configuration_blocks : [ ]
# A list of strings containing additional configuration blocks to add to the nginx http's server configuration (nginx-http.conf).
matrix_synapse_reverse_proxy_companion_http_additional_server_configuration_blocks : [ ]
# To increase request timeout in NGINX using proxy_read_timeout, proxy_connect_timeout, proxy_send_timeout, send_timeout directives
# Nginx Default: proxy_connect_timeout 60s; #Defines a timeout for establishing a connection with a proxied server
# Nginx Default: proxy_send_timeout 60s; #Sets a timeout for transmitting a request to the proxied server.
# Nginx Default: proxy_read_timeout 60s; #Defines a timeout for reading a response from the proxied server.
# Nginx Default: send_timeout 60s; #Sets a timeout for transmitting a response to the client.
#
# For more information visit:
# http://nginx.org/en/docs/http/ngx_http_proxy_module.html
# http://nginx.org/en/docs/http/ngx_http_core_module.html#send_timeout
# https://www.nginx.com/resources/wiki/start/topics/examples/fullexample2/
#
# Here we are sticking with nginx default values change this value carefully.
matrix_synapse_reverse_proxy_companion_proxy_connect_timeout : 60
matrix_synapse_reverse_proxy_companion_proxy_send_timeout : 60
matrix_synapse_reverse_proxy_companion_proxy_read_timeout : 60
matrix_synapse_reverse_proxy_companion_send_timeout : 60
# For OCSP purposes, we need to define a resolver at the `server{}` level or `http{}` level (we do the latter).
#
# Otherwise, we get warnings like this:
# > [warn] 22#22: no resolver defined to resolve r3.o.lencr.org while requesting certificate status, responder: r3.o.lencr.org, certificate: "/matrix/ssl/config/live/.../fullchain.pem"
#
# We point it to the internal Docker resolver, which likely delegates to nameservers defined in `/etc/resolv.conf`.
matrix_synapse_reverse_proxy_companion_http_level_resolver : 127.0 .0 .11
matrix_synapse_reverse_proxy_companion_hostname : "matrix-synapse-reverse-proxy-companion"
# matrix_synapse_reverse_proxy_companion_client_api_addr specifies the address where the Client-Server API is
matrix_synapse_reverse_proxy_companion_client_api_addr : 'matrix-synapse:{{ matrix_synapse_container_client_api_port }}'
# This needs to be equal or higher than the maximum upload size accepted by Synapse.
matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb : 50
# matrix_synapse_reverse_proxy_companion_federation_api_enabled specifies whether reverse proxying for the Federation (Server-Server) API should be done
matrix_synapse_reverse_proxy_companion_federation_api_enabled : true
# matrix_synapse_reverse_proxy_companion_federation_api_addr specifies the address where the Federation (Server-Server) API is
matrix_synapse_reverse_proxy_companion_federation_api_addr : 'matrix-synapse:{{ matrix_synapse_container_federation_api_plain_port }}'
matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb : "{{ (matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb | int) * 3 }}"
# A list of strings containing additional configuration blocks to add to the nginx vhost handling the Synapse Client-Server API
matrix_synapse_reverse_proxy_companion_synapse_client_api_additional_server_configuration_blocks : [ ]
# A list of strings containing additional configuration blocks to add to the nginx vhost handling the Synapse Federation (Server-Server) API
matrix_synapse_reverse_proxy_companion_synapse_federation_api_additional_server_configuration_blocks : [ ]
# synapse worker activation and endpoint mappings
matrix_synapse_reverse_proxy_companion_synapse_workers_enabled : false
matrix_synapse_reverse_proxy_companion_synapse_workers_list : [ ]
matrix_synapse_reverse_proxy_companion_synapse_generic_worker_client_server_locations : [ ]
matrix_synapse_reverse_proxy_companion_synapse_generic_worker_federation_locations : [ ]
matrix_synapse_reverse_proxy_companion_synapse_stream_writer_typing_stream_worker_client_server_locations : [ ]
matrix_synapse_reverse_proxy_companion_synapse_stream_writer_to_device_stream_worker_client_server_locations : [ ]
matrix_synapse_reverse_proxy_companion_synapse_stream_writer_account_data_stream_worker_client_server_locations : [ ]
matrix_synapse_reverse_proxy_companion_synapse_stream_writer_receipts_stream_worker_client_server_locations : [ ]
matrix_synapse_reverse_proxy_companion_synapse_stream_writer_presence_stream_worker_client_server_locations : [ ]
matrix_synapse_reverse_proxy_companion_synapse_media_repository_locations : [ ]
matrix_synapse_reverse_proxy_companion_synapse_user_dir_locations : [ ]
# synapse content caching
matrix_synapse_reverse_proxy_companion_synapse_cache_enabled : false
matrix_synapse_reverse_proxy_companion_synapse_cache_path : /tmp/synapse-cache
matrix_synapse_reverse_proxy_companion_synapse_cache_keys_zone_name : "STATIC"
matrix_synapse_reverse_proxy_companion_synapse_cache_keys_zone_size : "10m"
matrix_synapse_reverse_proxy_companion_synapse_cache_inactive_time : "48h"
matrix_synapse_reverse_proxy_companion_synapse_cache_max_size_mb : 1024
matrix_synapse_reverse_proxy_companion_synapse_cache_proxy_cache_valid_time : "24h"
# Controls whether matrix-synapse-reverse-proxy-companion trusts an upstream server's X-Forwarded-Proto header.
2024-01-14 17:42:14 +01:00
# The `matrix-synapse-reverse-proxy-companion` does not terminate SSL and always expects to be fronted by another reverse-proxy server.
2022-11-20 15:43:30 +01:00
# As such, it trusts the protocol scheme forwarded by the upstream proxy.
matrix_synapse_reverse_proxy_companion_trust_forwarded_proto : true
matrix_synapse_reverse_proxy_companion_x_forwarded_proto_value : "{{ '$http_x_forwarded_proto' if matrix_synapse_reverse_proxy_companion_trust_forwarded_proto else '$scheme' }}"
