<commit_before>Upgrading Synapse
=================

Before upgrading check if any special steps are required to upgrade from the
what you currently have installed to current version of synapse. The extra
instructions that may be required are listed later in this document.

1. If synapse was installed in a virtualenv then active that virtualenv before
   upgrading. If synapse is installed in a virtualenv in ``~/.synapse/`` then
   run:

   .. code:: bash

       source ~/.synapse/bin/activate

2. If synapse was installed using pip then upgrade to the latest version by
   running:

   .. code:: bash

       pip install --upgrade matrix-synapse

       # restart synapse
       synctl restart


   If synapse was installed using git then upgrade to the latest version by
   running:

   .. code:: bash

       # Pull the latest version of the master branch.
       git pull
       # Update the versions of synapse's python dependencies.
       python synapse/python_dependencies.py | xargs pip install --upgrade

       # restart synapse
       ./synctl restart


To check whether your update was sucessful, you can check the Server header
returned by the Client-Server API:

.. code:: bash

    # replace <host.name> with the hostname of your synapse homeserver.
    # You may need to specify a port (eg, :8448) if your server is not
    # configured on port 443.
    curl -kv https://<host.name>/_matrix/client/versions 2>&1 | grep "Server:"

Upgrading to v0.99.0
====================

In preparation for Synapse v1.0, you must update your TLS certificates from
self-signed ones to verifiable ones signed by a trusted root CA.

If you do not already have a certificate for your domain, the easiest way to get
one is with Synapse's new ACME support, which will use the ACME protocol to
provision a certificate automatically. By default, certificates will be obtained
from the publicly trusted CA Let's Encrypt.

For a sample configuration, please inspect the new ACME section in the example
generated config by running the ``generate-config`` executable. For example::

  ~/synapse/env3/bin/generate-config

You will need to provide Let's Encrypt (or other ACME provider) access to your
Synapse ACME challenge responder on port 80, at the domain of your homeserver.
This requires you either change the port of the ACME listener provided by
Synapse to a high port and reverse proxy to it, or use a tool like authbind to
allow Synapse to listen on port 80 without root access. (Do not run Synapse with
root permissions!)

You will need to back up or delete your self signed TLS certificate
(``example.com.tls.crt`` and ``example.com.tls.key``), Synapse's ACME
implementation will not overwrite them.

You may wish to use alternate methods such as Certbot to obtain a certificate
from Let's Encrypt, depending on your server configuration. Of course, if you
already have a valid certificate for your homeserver's domain, that can be
placed in Synapse's config directory without the need for ACME.

Upgrading to v0.34.0
====================

1. This release is the first to fully support Python 3. Synapse will now run on
   Python versions 3.5, or 3.6 (as well as 2.7). We recommend switching to
   Python 3, as it has been shown to give performance improvements.

   For users who have installed Synapse into a virtualenv, we recommend doing
   this by creating a new virtualenv. For example::

       virtualenv -p python3 ~/synapse/env3<commit_msg>Don't imply self-signed certs are required<commit_after>Upgrading Synapse
=================

Before upgrading check if any special steps are required to upgrade from the
what you currently have installed to current version of synapse. The extra
instructions that may be required are listed later in this document.

1. If synapse was installed in a virtualenv then active that virtualenv before
   upgrading. If synapse is installed in a virtualenv in ``~/.synapse/`` then
   run:

   .. code:: bash

       source ~/.synapse/bin/activate

2. If synapse was installed using pip then upgrade to the latest version by
   running:

   .. code:: bash

       pip install --upgrade matrix-synapse

       # restart synapse
       synctl restart


   If synapse was installed using git then upgrade to the latest version by
   running:

   .. code:: bash

       # Pull the latest version of the master branch.
       git pull
       # Update the versions of synapse's python dependencies.
       python synapse/python_dependencies.py | xargs pip install --upgrade

       # restart synapse
       ./synctl restart


To check whether your update was sucessful, you can check the Server header
returned by the Client-Server API:

.. code:: bash

    # replace <host.name> with the hostname of your synapse homeserver.
    # You may need to specify a port (eg, :8448) if your server is not
    # configured on port 443.
    curl -kv https://<host.name>/_matrix/client/versions 2>&1 | grep "Server:"

Upgrading to v0.99.0
====================

In preparation for Synapse v1.0, you must ensure your federation TLS
certificates are verifiable by signed by a trusted root CA.

If you do not already have a valid certificate for your domain, the easiest
way to get one is with Synapse's new ACME support, which will use the ACME
protocol to provision a certificate automatically. By default, certificates
will be obtained from the publicly trusted CA Let's Encrypt.

For a sample configuration, please inspect the new ACME section in the example
generated config by running the ``generate-config`` executable. For example::

  ~/synapse/env3/bin/generate-config

You will need to provide Let's Encrypt (or another ACME provider) access to
your Synapse ACME challenge responder on port 80, at the domain of your
homeserver. This requires you to either change the port of the ACME listener
provided by Synapse to a high port and reverse proxy to it, or use a tool
like ``authbind`` to allow Synapse to listen on port 80 without root access.
(Do not run Synapse with root permissions!)

If you are already using self-signed ceritifcates, you will need to back up
or delete them (files ``example.com.tls.crt`` and ``example.com.tls.key`` in
Synapse's root directory), Synapse's ACME implementation will not overwrite
them.

You may wish to use alternate methods such as Certbot to obtain a certificate
from Let's Encrypt, depending on your server configuration. Of course, if you
already have a valid certificate for your homeserver's domain, that can be
placed in Synapse's config directory without the need for any ACME setup.

Upgrading to v0.34.0
====================

1. This release is the first to fully support Python 3. Synapse will now run on
   Python versions 3.5, or 3.6 (as well as 2.7). We recommend switching to
   Python 3, as it has been shown to give performance improvements.

   For users who have installed Synapse into a virtualenv, we recommend doing
   this by creating a new virtualenv. For example::

       virtualenv -p python3 ~/synapse/env3
{'fraction_non_alphanumeric': 0.06707578136149565, 'fraction_numerical': 0.010560867703724847, 'mean_word_length': 3.6135615536537196, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '166057', 'n_tokens_mistral': 1894, 'n_tokens_neox': 1757, 'n_words': 1006}