From fe349b497e4b22bb409eb199b77479c5895af525 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 19 Sep 2019 18:20:01 +0100 Subject: [PATCH] Update the upgrade notes (#6050) * make it clear that if you installed from a package manager, you should use that to upgrade * Document the new way of getting the server version (cf #4878) * Write some words about downgrading. --- UPGRADE.rst | 80 +++++++++++++++++++++++++++++--------------- changelog.d/6050.doc | 1 + 2 files changed, 54 insertions(+), 27 deletions(-) create mode 100644 changelog.d/6050.doc diff --git a/UPGRADE.rst b/UPGRADE.rst index 53f3af4ed13c..4ede973a087b 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -2,52 +2,78 @@ 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 +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 activate that virtualenv before - upgrading. If synapse is installed in a virtualenv in ``~/synapse/env`` then - run: +* If Synapse was installed using `prebuilt packages + `_, you will need to follow the normal process + for upgrading those packages. - .. code:: bash +* If Synapse was installed from source, then: - source ~/synapse/env/bin/activate - -2. If synapse was installed using pip then upgrade to the latest version by - running: + 1. Activate the virtualenv before upgrading. For example, if Synapse is + installed in a virtualenv in ``~/synapse/env`` then run: - .. code:: bash + .. code:: bash - pip install --upgrade matrix-synapse[all] + source ~/synapse/env/bin/activate - # restart synapse - synctl restart + 2. If Synapse was installed using pip then upgrade to the latest version by + running: + .. code:: bash - If synapse was installed using git then upgrade to the latest version by - running: + pip install --upgrade matrix-synapse - .. code:: bash + If Synapse was installed using git then upgrade to the latest version by + running: - # Pull the latest version of the master branch. + .. code:: bash + git pull + pip install --upgrade . - # Update synapse and its python dependencies. - pip install --upgrade .[all] + 3. Restart Synapse: - # restart synapse - ./synctl restart + .. code:: bash + ./synctl restart -To check whether your update was successful, you can check the Server header -returned by the Client-Server API: +To check whether your update was successful, you can check the running server +version with: .. code:: bash - # replace 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:///_matrix/client/versions 2>&1 | grep "Server:" + # 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: + + .. code:: bash + + source env/bin/activate + # replace `1.3.0` accordingly: + pip install matrix-synapse==1.3.0 + +* Debian: + + .. code:: bash + + # 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.4.0 =================== diff --git a/changelog.d/6050.doc b/changelog.d/6050.doc new file mode 100644 index 000000000000..3d19c69bc468 --- /dev/null +++ b/changelog.d/6050.doc @@ -0,0 +1 @@ +Update the upgrade notes.