Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Update the upgrade notes #6050

Merged
merged 4 commits into from
Sep 19, 2019
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 51 additions & 27 deletions UPGRADE.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
<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:
richvdh marked this conversation as resolved.
Show resolved Hide resolved

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
richvdh marked this conversation as resolved.
Show resolved Hide resolved
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
richvdh marked this conversation as resolved.
Show resolved Hide resolved
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
richvdh marked this conversation as resolved.
Show resolved Hide resolved
running:

# Pull the latest version of the master branch.
.. code:: bash
richvdh marked this conversation as resolved.
Show resolved Hide resolved
git pull
pip install --upgrade .

# Update synapse and its python dependencies.
pip install --upgrade .[all]
3. Restart synapse:
richvdh marked this conversation as resolved.
Show resolved Hide resolved

# 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
pip install matrix-synapse==<version>
richvdh marked this conversation as resolved.
Show resolved Hide resolved

* 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be nice to add the git version. I assume it's just a:

git checkout release-<version>
pip install --upgrade .

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm kinda assuming that if you've installed from git in the first place, you know how to go back to an earlier tag.


Upgrading to v1.4.0
===================
Expand Down
1 change: 1 addition & 0 deletions changelog.d/6050.doc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Update the upgrade notes.