diff --git a/docs/configuring-playbook-own-webserver.md b/docs/configuring-playbook-own-webserver.md index 9e3391c3..448f5d03 100644 --- a/docs/configuring-playbook-own-webserver.md +++ b/docs/configuring-playbook-own-webserver.md @@ -6,28 +6,50 @@ 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. -All it takes is: -1) making 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` +## Preparation -2) editing your configuration file (`inventory/matrix./vars.yml`): +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` + +2) Edit your configuration file (`inventory/matrix./vars.yml`) to disable the integrated nginx server: ```yaml matrix_nginx_proxy_enabled: false +``` + +3) **If you'll manage SSL certificates by yourself**, edit your configuration file (`inventory/matrix./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. -# If you use an external nginx, we'll generate some configuration for you in `/matrix/nginx-proxy/conf.d/`. -# You might need to tweak the protocol list (removing `TLSv1.3`) to suit your nginx version. -matrix_nginx_proxy_ssl_protocols: "TLSv1.1 TLSv1.2 TLSv1.3" + +## 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.1 TLSv1.2" ``` -**Note**: even if you do this, in order [to install](installing.md), this playbook still expects port 80 to be available. **Please manually stop your other webserver while installing**. You can start it back again afterwards. -**If your own webserver is nginx**, you can most likely directly use the config files installed by this playbook at: `/matrix/nginx-proxy/conf.d`. Just include them in your `nginx.conf` like this: `include /matrix/nginx-proxy/conf.d/*.conf;`. Please note that if your nginx version is old, it might not like our default SSL protocols (particularly the fact that `TLSv1.3` is enabled). You can override the protocol list by redefining the `matrix_nginx_proxy_ssl_protocols` variable. +## Using your own external Apache webserver -**If your own webserver is not nginx**, you can still take a look at the sample files in `/matrix/nginx-proxy/conf.d`, and: +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. -- ensure you set up (separate) vhosts that proxy for both Riot (`localhost:8765`) and Matrix Synapse (`localhost:8008`) -- ensure that the `/.well-known/acme-challenge` location for each "port=80 vhost" gets proxied to `http://localhost:2402` (controlled by `matrix_ssl_lets_encrypt_certbot_standalone_http_port`) for automated SSL renewal to work +## Using another external webserver -- ensure that you restart/reload your webserver once in a while, so that renewed SSL certificates would take effect (once a month should be enough) +Feel free to look at the [examples/apache](../examples/apache) directory, or the [template files in the matrix-nginx-proxy role](../roles/matrix-nginx-proxy/templates/conf.d/). diff --git a/examples/apache/README.md b/examples/apache/README.md new file mode 100644 index 00000000..33183b9c --- /dev/null +++ b/examples/apache/README.md @@ -0,0 +1,17 @@ +# Apache reverse-proxy + +This directory contains sample files that show you how to do reverse-proxying using Apache. + +This is for when you wish to have your own Apache webserver sitting in front of Matrix services installed by this playbook. +See the [Using your own webserver, instead of this playbook's nginx proxy](../../docs/configuring-playbook-own-webserver.md) documentation page. + +To use your own Apache reverse-proxy, you first need to disable the integrated nginx server. +You do that with the following custom configuration (`inventory/matrix./vars.yml`): + +```yaml +matrix_nginx_proxy_enabled: false +``` + +You can then use the configuration files from this directory as an example for how to configure your Apache server. + +**NOTE**: this is just an example and may not be entirely accurate. It may also not cover other use cases (enabling various services or bridges requires additional reverse-proxying configuration). diff --git a/examples/apache/matrix-riot-web.conf b/examples/apache/matrix-riot-web.conf new file mode 100644 index 00000000..263136ee --- /dev/null +++ b/examples/apache/matrix-riot-web.conf @@ -0,0 +1,41 @@ +# This is a sample file demonstrating how to set up reverse-proxy for the riot.DOMAIN. +# If you're not using Riot (`matrix_riot_web_enabled: false`), you won't need this. + + + ServerName riot.DOMAIN + + # Map /.well-known/acme-challenge to the certbot server + # If you manage SSL certificates by yourself, this will differ. + + ProxyPreserveHost On + ProxyRequests Off + ProxyVia On + ProxyPass http://localhost:2402/.well-known/acme-challenge + + + Redirect permanent / https://riot.DOMAIN/ + + + + ServerName riot.DOMAIN + + SSLEngine On + + # If you manage SSL certificates by yourself, these paths will differ. + SSLCertificateFile /matrix/ssl/config/live/riot.DOMAIN/fullchain.pem + SSLCertificateKeyFile /matrix/ssl/config/live/riot.DOMAIN/privkey.pem + + SSLProxyEngine on + SSLProxyProtocol +TLSv1.1 +TLSv1.2 +TLSv1.3 + SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH + + ProxyPreserveHost On + ProxyRequests Off + ProxyVia On + + ProxyPass / http://localhost:8765/ + ProxyPassReverse / http://localhost:8765/ + + ErrorLog ${APACHE_LOG_DIR}/riot.DOMAIN-error.log + CustomLog ${APACHE_LOG_DIR}/riot.DOMAIN-access.log combined + diff --git a/examples/apache/matrix-synapse.conf b/examples/apache/matrix-synapse.conf new file mode 100644 index 00000000..b5e11d04 --- /dev/null +++ b/examples/apache/matrix-synapse.conf @@ -0,0 +1,73 @@ +# This is a sample file demonstrating how to set up reverse-proxy for the matrix.DOMAIN + + + ServerName matrix.DOMAIN + + # Map /.well-known/acme-challenge to the certbot server + # If you manage SSL certificates by yourself, this will differ. + + ProxyPreserveHost On + ProxyRequests Off + ProxyVia On + ProxyPass http://localhost:2402/.well-known/acme-challenge + + + Redirect permanent / https://matrix.DOMAIN/ + + + + ServerName matrix.DOMAIN + + SSLEngine On + + # If you manage SSL certificates by yourself, these paths will differ. + SSLCertificateFile /matrix/ssl/config/live/matrix.DOMAIN/fullchain.pem + SSLCertificateKeyFile /matrix/ssl/config/live/matrix.DOMAIN/privkey.pem + + SSLProxyEngine on + SSLProxyProtocol +TLSv1.1 +TLSv1.2 +TLSv1.3 + SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH + + ProxyPreserveHost On + ProxyRequests Off + ProxyVia On + + # Keep some URIs free for different proxy/location + ProxyPassMatch ^/.well-known/matrix/client ! + ProxyPassMatch ^/_matrix/identity ! + ProxyPassMatch ^/_matrix/client/r0/user_directory/search ! + + # Proxy all remaining traffic to Synapse + ProxyPass / http://localhost:8008/ + ProxyPassReverse / http://localhost:8008/ + + # Map /.well-known/matrix/client for client discovery + Alias /.well-known/matrix/client /matrix/static-files/.well-known/matrix/client + + Require all granted + + + Header always set Content-Type "application/json" + Header always set Access-Control-Allow-Origin "*" + + + AllowOverride All + # Apache 2.4: + Require all granted + # Or for Apache 2.2: + #order allow,deny + + + # Map /_matrix/identity to the identity server + + ProxyPass http://localhost:8090/_matrix/identity + + + # Map /_matrix/client/r0/user_directory/search to the identity server + + ProxyPass http://localhost:8090/_matrix/client/r0/user_directory/search + + + ErrorLog ${APACHE_LOG_DIR}/matrix.DOMAIN-error.log + CustomLog ${APACHE_LOG_DIR}/matrix.DOMAIN-access.log combined +