Merge pull request #2468 from maxidor/develop

Clarify recommended network setup
This commit is contained in:
Richard van der Hoff 2017-09-25 16:37:33 +01:00 committed by GitHub
commit cacfa04cb6

View File

@ -200,11 +200,11 @@ different. See `the spec`__ for more information on key management.)
.. __: `key_management`_ .. __: `key_management`_
The default configuration exposes two HTTP ports: 8008 and 8448. Port 8008 is The default configuration exposes two HTTP ports: 8008 and 8448. Port 8008 is
configured without TLS; it is not recommended this be exposed outside your configured without TLS; it should be behind a reverse proxy for TLS/SSL
local network. Port 8448 is configured to use TLS with a self-signed termination on port 443 which in turn should be used for clients. Port 8448
certificate. This is fine for testing with but, to avoid your clients is configured to use TLS with a self-signed certificate. If you would like
complaining about the certificate, you will almost certainly want to use to do initial test with a client without having to setup a reverse proxy,
another certificate for production purposes. (Note that a self-signed you can temporarly use another certificate. (Note that a self-signed
certificate is fine for `Federation`_). You can do so by changing certificate is fine for `Federation`_). You can do so by changing
``tls_certificate_path``, ``tls_private_key_path`` and ``tls_dh_params_path`` ``tls_certificate_path``, ``tls_private_key_path`` and ``tls_dh_params_path``
in ``homeserver.yaml``; alternatively, you can use a reverse-proxy, but be sure in ``homeserver.yaml``; alternatively, you can use a reverse-proxy, but be sure
@ -283,10 +283,16 @@ Connecting to Synapse from a client
The easiest way to try out your new Synapse installation is by connecting to it The easiest way to try out your new Synapse installation is by connecting to it
from a web client. The easiest option is probably the one at from a web client. The easiest option is probably the one at
http://riot.im/app. You will need to specify a "Custom server" when you log on http://riot.im/app. You will need to specify a "Custom server" when you log on
or register: set this to ``https://localhost:8448`` - remember to specify the or register: set this to ``https://domain.tld`` if you setup a reverse proxy
port (``:8448``) unless you changed the configuration. (Leave the identity following the recommended setup, or ``https://localhost:8448`` - remember to specify the
port (``:8448``) if not ``:443`` unless you changed the configuration. (Leave the identity
server as the default - see `Identity servers`_.) server as the default - see `Identity servers`_.)
If using port 8448 you will run into errors until you accept the self-signed
certificate. You can easily do this by going to ``https://localhost:8448``
directly with your browser and accept the presented certificate. You can then
go back in your web client and proceed further.
If all goes well you should at least be able to log in, create a room, and If all goes well you should at least be able to log in, create a room, and
start sending messages. start sending messages.
@ -593,8 +599,9 @@ you to run your server on a machine that might not have the same name as your
domain name. For example, you might want to run your server at domain name. For example, you might want to run your server at
``synapse.example.com``, but have your Matrix user-ids look like ``synapse.example.com``, but have your Matrix user-ids look like
``@user:example.com``. (A SRV record also allows you to change the port from ``@user:example.com``. (A SRV record also allows you to change the port from
the default 8448. However, if you are thinking of using a reverse-proxy, be the default 8448. However, if you are thinking of using a reverse-proxy on the
sure to read `Reverse-proxying the federation port`_ first.) federation port, which is not recommended, be sure to read
`Reverse-proxying the federation port`_ first.)
To use a SRV record, first create your SRV record and publish it in DNS. This To use a SRV record, first create your SRV record and publish it in DNS. This
should have the format ``_matrix._tcp.<yourdomain.com> <ttl> IN SRV 10 0 <port> should have the format ``_matrix._tcp.<yourdomain.com> <ttl> IN SRV 10 0 <port>
@ -674,7 +681,7 @@ For information on how to install and use PostgreSQL, please see
Using a reverse proxy with Synapse Using a reverse proxy with Synapse
================================== ==================================
It is possible to put a reverse proxy such as It is recommended to put a reverse proxy such as
`nginx <https://nginx.org/en/docs/http/ngx_http_proxy_module.html>`_, `nginx <https://nginx.org/en/docs/http/ngx_http_proxy_module.html>`_,
`Apache <https://httpd.apache.org/docs/current/mod/mod_proxy_http.html>`_ or `Apache <https://httpd.apache.org/docs/current/mod/mod_proxy_http.html>`_ or
`HAProxy <http://www.haproxy.org/>`_ in front of Synapse. One advantage of `HAProxy <http://www.haproxy.org/>`_ in front of Synapse. One advantage of
@ -692,9 +699,9 @@ federation port has a number of pitfalls. It is possible, but be sure to read
`Reverse-proxying the federation port`_. `Reverse-proxying the federation port`_.
The recommended setup is therefore to configure your reverse-proxy on port 443 The recommended setup is therefore to configure your reverse-proxy on port 443
for client connections, but to also expose port 8448 for server-server to port 8008 of synapse for client connections, but to also directly expose port
connections. All the Matrix endpoints begin ``/_matrix``, so an example nginx 8448 for server-server connections. All the Matrix endpoints begin ``/_matrix``,
configuration might look like:: so an example nginx configuration might look like::
server { server {
listen 443 ssl; listen 443 ssl;