Update own-webserver guide and add sample Apache configuration

This supersedes #59 (Github Pull Request),
which was greatly beneficial in creating our sample Apache configuration.
This commit is contained in:
Slavi Pantaleev 2019-02-01 16:51:18 +02:00
parent 8681a5dc69
commit 5e8a7fd05b
4 changed files with 166 additions and 13 deletions

View file

@ -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, 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. 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.<your-domain>/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.<your-domain>/vars.yml`) to disable the integrated nginx server:
```yaml ```yaml
matrix_nginx_proxy_enabled: false matrix_nginx_proxy_enabled: false
# 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"
``` ```
**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. 3) **If you'll manage SSL certificates by yourself**, edit your configuration file (`inventory/matrix.<your-domain>/vars.yml`) to disable SSL certificate retrieval:
**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. ```yaml
matrix_ssl_retrieval_method: none
```
**If your own webserver is not nginx**, you can still take a look at the sample files in `/matrix/nginx-proxy/conf.d`, and: **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.
- 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 your own external nginx 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) 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"
```
## 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 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/matrix-nginx-proxy/templates/conf.d/).

17
examples/apache/README.md Normal file
View file

@ -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.<your-domain>/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).

View file

@ -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.
<VirtualHost *:80>
ServerName riot.DOMAIN
# Map /.well-known/acme-challenge to the certbot server
# If you manage SSL certificates by yourself, this will differ.
<Location /.well-known/acme-challenge>
ProxyPreserveHost On
ProxyRequests Off
ProxyVia On
ProxyPass http://localhost:2402/.well-known/acme-challenge
</Location>
Redirect permanent / https://riot.DOMAIN/
</VirtualHost>
<VirtualHost *:443>
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
</VirtualHost>

View file

@ -0,0 +1,73 @@
# This is a sample file demonstrating how to set up reverse-proxy for the matrix.DOMAIN
<VirtualHost *:80>
ServerName matrix.DOMAIN
# Map /.well-known/acme-challenge to the certbot server
# If you manage SSL certificates by yourself, this will differ.
<Location /.well-known/acme-challenge>
ProxyPreserveHost On
ProxyRequests Off
ProxyVia On
ProxyPass http://localhost:2402/.well-known/acme-challenge
</Location>
Redirect permanent / https://matrix.DOMAIN/
</VirtualHost>
<VirtualHost *:443>
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
<Files "/matrix/static-files/.well-known/matrix/client">
Require all granted
</Files>
<Location "/.well-known/matrix/client>
Header always set Content-Type "application/json"
Header always set Access-Control-Allow-Origin "*"
</Location>
<Directory /matrix/static-files/.well-known/matrix/>
AllowOverride All
# Apache 2.4:
Require all granted
# Or for Apache 2.2:
#order allow,deny
</Directory>
# Map /_matrix/identity to the identity server
<Location /_matrix/identity>
ProxyPass http://localhost:8090/_matrix/identity
</Location>
# Map /_matrix/client/r0/user_directory/search to the identity server
<Location /_matrix/client/r0/user_directory/search>
ProxyPass http://localhost:8090/_matrix/client/r0/user_directory/search
</Location>
ErrorLog ${APACHE_LOG_DIR}/matrix.DOMAIN-error.log
CustomLog ${APACHE_LOG_DIR}/matrix.DOMAIN-access.log combined
</VirtualHost>