You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
220 lines
12 KiB
220 lines
12 KiB
# Using your own webserver, instead of this playbook's nginx proxy (optional, advanced)
|
|
|
|
**Note**: the playbook is [in the process of moving to Traefik](../CHANGELOG.md#reverse-proxy-configuration-changes-and-initial-traefik-support). The documentation below should be correct, but things will change soon.
|
|
|
|
By default, this playbook installs its own nginx webserver (called `matrix-nginx-proxy`, in a Docker container) which listens on ports 80 and 443.
|
|
If that's alright, you can skip this.
|
|
|
|
If you don't want this playbook's nginx webserver to take over your server's 80/443 ports like that,
|
|
and you'd like to use your own webserver (be it nginx, Apache, Varnish Cache, etc.), you can.
|
|
|
|
There are **2 ways you can go about it**, if you'd like to use your own webserver:
|
|
|
|
- [Method 1: Disabling the integrated nginx reverse-proxy webserver](#method-1-disabling-the-integrated-nginx-reverse-proxy-webserver)
|
|
|
|
- [Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy](#method-2-fronting-the-integrated-nginx-reverse-proxy-webserver-with-another-reverse-proxy)
|
|
|
|
|
|
## Method 1: Disabling the integrated nginx reverse-proxy webserver
|
|
|
|
This method is about completely disabling the integrated nginx reverse-proxy webserver and replicating its behavior using another webserver.
|
|
|
|
If that other webserver is `nginx`, you'd be able to include configuration files generated by the playbook into your `nginx` webserver.
|
|
|
|
If you'd like to use another webserver (not `nginx`), you'd need to do things manually. We have examples for other webservers below.
|
|
|
|
For an alternative (which keeps `matrix-nginx-proxy` around and connects your other reverse-proxy with it), make sure to check Method #2.
|
|
|
|
### Preparation
|
|
|
|
No matter which external webserver you decide to go with, you'll need to:
|
|
|
|
1) Make sure your web server user (something like `http`, `apache`, `www-data`, `nginx`) is part of the `matrix` group. You should run something like this: `usermod -a -G matrix nginx`. This allows your webserver user to access files owned by the `matrix` group. When using an external nginx webserver, this allows it to read configuration files from `/matrix/nginx-proxy/conf.d`. When using another server, it would make other files, such as `/matrix/static-files/.well-known`, accessible to it.
|
|
|
|
2) Edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`)
|
|
- to disable the integrated nginx server:
|
|
|
|
```yaml
|
|
matrix_nginx_proxy_enabled: false
|
|
```
|
|
- if using an external server on another host, add the `<service>_http_host_bind_port` or `<service>_http_bind_port` variables for the services that will be exposed by the external server on the other host. The actual name of the variable is listed in the `roles/<service>/defaults/vars.yml` file for each service. Most variables follow the `<service>_http_host_bind_port` format.
|
|
|
|
These variables will make Docker expose the ports on all network interfaces instead of localhost only.
|
|
[Keep in mind that there are some security concerns if you simply proxy everything.](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints)
|
|
|
|
Here are the variables required for the default configuration (Synapse and Element)
|
|
```
|
|
matrix_synapse_reverse_proxy_companion_container_client_api_host_bind_port: '0.0.0.0:8008'
|
|
matrix_synapse_reverse_proxy_companion_container_federation_api_host_bind_port: '0.0.0.0:8048'
|
|
matrix_client_element_container_http_host_bind_port: "0.0.0.0:8765"
|
|
```
|
|
|
|
3) **If you'll manage SSL certificates by yourself**, edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to disable SSL certificate retrieval:
|
|
|
|
```yaml
|
|
matrix_ssl_retrieval_method: none
|
|
```
|
|
|
|
**Note**: During [installation](installing.md), unless you've disabled SSL certificate management (`matrix_ssl_retrieval_method: none`), the playbook would need 80 to be available, in order to retrieve SSL certificates. **Please manually stop your other webserver while installing**. You can start it back up afterwards.
|
|
|
|
### Using your own external nginx webserver
|
|
|
|
Once you've followed the [Preparation](#preparation) guide above, it's time to set up your external nginx server.
|
|
|
|
Even with `matrix_nginx_proxy_enabled: false`, the playbook still generates some helpful files for you in `/matrix/nginx-proxy/conf.d`.
|
|
Those configuration files are adapted for use with an external web server (one not running in the container network).
|
|
|
|
You can most likely directly use the config files installed by this playbook at: `/matrix/nginx-proxy/conf.d`. Just include them in your own `nginx.conf` like this: `include /matrix/nginx-proxy/conf.d/*.conf;`
|
|
|
|
Note that if your nginx version is old, it might not like our default choice of SSL protocols (particularly the fact that the brand new `TLSv1.3` protocol is enabled). You can override the protocol list by redefining the `matrix_nginx_proxy_ssl_protocols` variable. Example:
|
|
|
|
```yaml
|
|
# Custom protocol list (removing `TLSv1.3`) to suit your nginx version.
|
|
matrix_nginx_proxy_ssl_protocols: "TLSv1.2"
|
|
```
|
|
|
|
If you are experiencing issues, try updating to a newer version of Nginx. As a data point in May 2021 a user reported that Nginx 1.14.2 was not working for them. They were getting errors about socket leaks. Updating to Nginx 1.19 fixed their issue.
|
|
|
|
### Using your own external Apache webserver
|
|
|
|
Once you've followed the [Preparation](#preparation) guide above, you can take a look at the [examples/apache](../examples/apache) directory for a sample configuration.
|
|
|
|
### Using your own external caddy webserver
|
|
|
|
After following the [Preparation](#preparation) guide above, you can take a look at the [examples/caddy](../examples/caddy) directory and [examples/caddy2](../examples/caddy2) directory for a sample configuration for Caddy v1 and v2, respectively.
|
|
|
|
### Using your own HAproxy reverse proxy
|
|
After following the [Preparation](#preparation) guide above, you can take a look at the [examples/haproxy](../examples/haproxy) directory for a sample configuration. In this case HAproxy is used as a reverse proxy and a simple Nginx container is used to serve statically `.well-known` files.
|
|
|
|
### Using another external webserver
|
|
|
|
Feel free to look at the [examples/apache](../examples/apache) directory, or the [template files in the matrix-nginx-proxy role](../roles/custom/matrix-nginx-proxy/templates/nginx/conf.d/).
|
|
|
|
|
|
## Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy
|
|
|
|
This method is about leaving the integrated nginx reverse-proxy webserver be, but making it not get in the way (using up important ports, trying to retrieve SSL certificates, etc.).
|
|
|
|
If you wish to use another webserver, the integrated nginx reverse-proxy webserver usually gets in the way because it attempts to fetch SSL certificates and binds to ports 80, 443 and 8448 (if Matrix Federation is enabled).
|
|
|
|
You can disable such behavior and make the integrated nginx reverse-proxy webserver only serve traffic locally (or over a local network).
|
|
|
|
You would need some configuration like this:
|
|
|
|
```yaml
|
|
matrix_playbook_reverse_proxy_type: other-on-same-host
|
|
|
|
# Do not listen for HTTP on port 80 globally (default), listen on the loopback interface.
|
|
# If you'd like, you can make it use the local network as well and reverse-proxy from another local machine.
|
|
matrix_nginx_proxy_container_http_host_bind_port: '127.0.0.1:81'
|
|
|
|
# Likewise, expose the Matrix Federation port on the loopback interface.
|
|
# Since `matrix_nginx_proxy_https_enabled` is set to `false`, this federation port will serve HTTP traffic.
|
|
# If you'd like, you can make it use the local network as well and reverse-proxy from another local machine.
|
|
#
|
|
# You'd most likely need to expose it publicly on port 8448 (8449 was chosen for the local port to prevent overlap).
|
|
matrix_nginx_proxy_container_federation_host_bind_port: '127.0.0.1:8449'
|
|
|
|
# Coturn relies on SSL certificates that have already been obtained.
|
|
# Since we don't obtain any certificates in this `other-on-same-host` mode, it won't work by default.
|
|
# An alternative is to tweak some of: `matrix_coturn_tls_enabled`, `matrix_coturn_tls_cert_path` and `matrix_coturn_tls_key_path`.
|
|
matrix_coturn_enabled: false
|
|
```
|
|
|
|
With this, nginx would still be in use, but it would not bother with anything SSL related or with taking up public ports.
|
|
|
|
All services would be served locally on `127.0.0.1:81` and `127.0.0.1:8449` (as per the example configuration above).
|
|
|
|
You can then set up another reverse-proxy server on ports 80/443/8448 for all of the expected domains and make traffic go to these local ports.
|
|
The expected domains vary depending on the services you have enabled (`matrix.DOMAIN` for sure; `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN` are optional).
|
|
|
|
### Sample configuration for running behind Traefik 2.0
|
|
|
|
To run behind Traefik, you can:
|
|
|
|
- use a [Playbook-managed Traefik installation](#playbook-managed-traefik-installation)
|
|
- or, use [Your own Traefik server (not managed by the playbook)](#your-own-traefik-server-not-managed-by-the-playbook)
|
|
|
|
#### Playbook-managed Traefik installation
|
|
|
|
The playbook can install and manage Traefik for you using the [com.devture.ansible.role.traefik](https://github.com/devture/com.devture.ansible.role.traefik) role.
|
|
|
|
It's simplest if you go with this method. You will need the following configuration:
|
|
|
|
```yaml
|
|
matrix_playbook_reverse_proxy_type: playbook-managed-traefik
|
|
|
|
devture_traefik_ssl_email_address: YOUR_EMAIL_ADDRESS
|
|
```
|
|
|
|
#### Your own Traefik server (not managed by the playbook)
|
|
|
|
If you'd like to run Traefik yourself, you can use configuration like this:
|
|
|
|
```yaml
|
|
matrix_playbook_reverse_proxy_type: other-traefik-container
|
|
|
|
matrix_playbook_reverse_proxyable_services_additional_network: your-traefik-network
|
|
```
|
|
|
|
In this mode all roles will still have Traefik labels attached. You will, however, need to configure your Traefik instance and its entrypoints.
|
|
|
|
By default, the playbook congiures services use a `web-secure` (443) and `matrix-federation` (8448) entrypoints, as well as a `default` certificate resolver.
|
|
|
|
Below is some configuration for running Traefik yourself (although we recommend using a [playbook-managed Traefik installation](#playbook-managed-traefik-installation)).
|
|
|
|
Note that this configuration on its own does **not** redirect traffic on port 80 (plain HTTP) to port 443 for HTTPS, which may cause some issues, since the built-in Nginx proxy usually does this. If you are not already doing this in Traefik, it can be added to Traefik in a [file provider](https://docs.traefik.io/v2.0/providers/file/) as follows:
|
|
|
|
```toml
|
|
[http]
|
|
[http.routers]
|
|
[http.routers.redirect-http]
|
|
entrypoints = ["web"] # The 'web' entrypoint must bind to port 80
|
|
rule = "HostRegexp(`{host:.+}`)" # Change if you don't want to redirect all hosts to HTTPS
|
|
service = "dummy" # Unused, but all routers need services (for now)
|
|
middlewares = ["https"]
|
|
[http.services]
|
|
[http.services.dummy.loadbalancer]
|
|
[[http.services.dummy.loadbalancer.servers]]
|
|
url = "localhost"
|
|
[http.middlewares]
|
|
[http.middlewares.https.redirectscheme]
|
|
scheme = "https"
|
|
permanent = true
|
|
```
|
|
|
|
You can use the following `docker-compose.yml` as example to launch Traefik.
|
|
|
|
```yaml
|
|
version: "3.3"
|
|
|
|
services:
|
|
|
|
traefik:
|
|
image: "docker.io/traefik:v2.9.6"
|
|
restart: always
|
|
container_name: "traefik"
|
|
networks:
|
|
- traefik
|
|
command:
|
|
- "--api.insecure=true"
|
|
- "--providers.docker=true"
|
|
- "--providers.docker.network=traefik"
|
|
- "--providers.docker.exposedbydefault=false"
|
|
- "--entrypoints.web-secure.address=:443"
|
|
- "--entrypoints.federation.address=:8448"
|
|
- "--certificatesresolvers.default.acme.tlschallenge=true"
|
|
- "--certificatesresolvers.default.acme.email=YOUR EMAIL"
|
|
- "--certificatesresolvers.default.acme.storage=/letsencrypt/acme.json"
|
|
ports:
|
|
- "443:443"
|
|
- "8448:8448"
|
|
volumes:
|
|
- "./letsencrypt:/letsencrypt"
|
|
- "/var/run/docker.sock:/var/run/docker.sock:ro"
|
|
|
|
networks:
|
|
traefik:
|
|
external: true
|
|
```
|