diff options
| -rw-r--r-- | UPGRADE.rst | 80 | ||||
| -rw-r--r-- | changelog.d/6050.doc | 1 |
2 files changed, 54 insertions, 27 deletions
diff --git a/UPGRADE.rst b/UPGRADE.rst index 53f3af4ed1..4ede973a08 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 + <INSTALL.md#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 <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:" + # 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 0000000000..3d19c69bc4 --- /dev/null +++ b/changelog.d/6050.doc @@ -0,0 +1 @@ +Update the upgrade notes. |