UPGRADE.rst

Upgrading to v1.20.0

Shared rooms endpoint (MSC2666)

This release contains a new unstable endpoint /_matrix/client/unstable/uk.half-shot.msc2666/user/shared_rooms/.* for fetching rooms one user has in common with another. This feature requires the update_user_directory config flag to be True. If you are you are using a synapse.app.user_dir worker, requests to this endpoint must be handled by that worker. See docs/workers.md for more details.

Upgrading Synapse

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

• If Synapse was installed using prebuilt packages, you will need to follow the normal process for upgrading those packages.

• If Synapse was installed from source, then:

  1. Activate the virtualenv before upgrading. For example, if Synapse is installed in a virtualenv in ~/synapse/env then run:

     source ~/synapse/env/bin/activate

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

     pip install --upgrade matrix-synapse

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

     git pull
     pip install --upgrade .

  3. Restart Synapse:

     ./synctl restart

To check whether your update was successful, you can check the running server version with:

# you may need to replace 'localhost:8008' if synapse is not configured
# to listen on port 8008.

curl http://localhost:8008/_synapse/admin/v1/server_version

Rolling back to older versions

Rolling back to previous releases can be difficult, due to database schema changes between releases. Where we have been able to test the rollback process, this will be noted below.

In general, you will need to undo any changes made during the upgrade process, for example:

• pip:

  source env/bin/activate
  # replace `1.3.0` accordingly:
  pip install matrix-synapse==1.3.0

• Debian:

  # replace `1.3.0` and `stretch` accordingly:
  wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb
  dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb

Upgrading to v1.21.0

New HTML templates

A new HTML template, password_reset_confirmation.html, has been added to the synapse/res/templates directory. If you are using a custom template directory, you may want to copy the template over and modify it.

Note that as of v1.20.0, templates do not need to be included in custom template directories for Synapse to start. The default templates will be used if a custom template cannot be found.

This page will appear to the user after clicking a password reset link that has been emailed to them.

To complete password reset, the page must include a way to make a POST request to /_synapse/client/password_reset/{medium}/submit_token with the query parameters from the original link, presented as a URL-encoded form. See the file itself for more details.

Upgrading to v1.18.0

Docker -py3 suffix will be removed in future versions

From 10th August 2020, we will no longer publish Docker images with the -py3 tag suffix. The images tagged with the -py3 suffix have been identical to the non-suffixed tags since release 0.99.0, and the suffix is obsolete.

On 10th August, we will remove the latest-py3 tag. Existing per-release tags (such as v1.18.0-py3) will not be removed, but no new -py3 tags will be added.

Scripts relying on the -py3 suffix will need to be updated.