From 679193744d89756721ec16369647ae05cb4cbd31 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 18 Sep 2019 12:06:00 +0100 Subject: [PATCH 1/4] Update the upgrade notes * 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 | 78 +++++++++++++++++++++++++++++--------------- changelog.d/6050.doc | 1 + 2 files changed, 52 insertions(+), 27 deletions(-) create mode 100644 changelog.d/6050.doc diff --git a/UPGRADE.rst b/UPGRADE.rst index 5aaf804902ed..480ee3e69c6c 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -2,52 +2,76 @@ 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 + pip install matrix-synapse== + +* 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. From d80a0b07cbb03477c2d2a81f0be8084f251e2898 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 19 Sep 2019 12:32:49 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-Authored-By: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- UPGRADE.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/UPGRADE.rst b/UPGRADE.rst index 480ee3e69c6c..49e5affbf8bc 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -9,30 +9,30 @@ instructions that may be required are listed later in this document. `_, you will need to follow the normal process for upgrading those packages. -* If synapse was installed from source, then: +* If Synapse was installed from source, then: - 1. Activate the virtualenv before upgrading. For example, if synapse is + 1. Activate the virtualenv before upgrading. For example, if Synapse is installed in a virtualenv in ``~/synapse/env`` then run: .. code:: bash source ~/synapse/env/bin/activate - 2. If synapse was installed using pip then upgrade to the latest version by + 2. If Synapse was installed using pip then upgrade to the latest version by running: .. code:: bash pip install --upgrade matrix-synapse - If synapse was installed using git then upgrade to the latest version by + If Synapse was installed using git then upgrade to the latest version by running: .. code:: bash git pull pip install --upgrade . - 3. Restart synapse: + 3. Restart Synapse: .. code:: bash From 874365de89a77023d5be1086dbd77eef166a6c0e Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 19 Sep 2019 12:34:13 +0100 Subject: [PATCH 3/4] fix formatting --- UPGRADE.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/UPGRADE.rst b/UPGRADE.rst index 49e5affbf8bc..15bb48e971b1 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -29,14 +29,15 @@ instructions that may be required are listed later in this document. running: .. code:: bash + git pull pip install --upgrade . - 3. Restart Synapse: + 3. Restart Synapse: - .. code:: bash + .. code:: bash - ./synctl restart + ./synctl restart To check whether your update was successful, you can check the running server version with: From b5cb8e111d6ef310e52bdd0e419a3aa375b572da Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 19 Sep 2019 12:35:54 +0100 Subject: [PATCH 4/4] Update UPGRADE.rst --- UPGRADE.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/UPGRADE.rst b/UPGRADE.rst index 15bb48e971b1..015adf3ac079 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -64,7 +64,8 @@ for example: .. code:: bash source env/bin/activate - pip install matrix-synapse== + # replace `1.3.0` accordingly: + pip install matrix-synapse==1.3.0 * Debian: