diff options
| -rw-r--r-- | README.rst | 67 | ||||
| -rw-r--r-- | UPGRADE.rst | 67 | ||||
| -rw-r--r-- | changelog.d/4260.misc | 1 |
3 files changed, 82 insertions, 53 deletions
diff --git a/README.rst b/README.rst index 8c55dd7894..664a0ea03f 100644 --- a/README.rst +++ b/README.rst @@ -86,7 +86,7 @@ Synapse is the reference Python/Twisted Matrix homeserver implementation. System requirements: - POSIX-compliant system (tested on Linux & OS X) -- Python 2.7 +- Python 3.5, 3.6, or 2.7 - At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org Installing from source @@ -101,13 +101,13 @@ header files for Python C extensions. Installing prerequisites on Ubuntu or Debian:: - sudo apt-get install build-essential python2.7-dev libffi-dev \ + sudo apt-get install build-essential python3-dev libffi-dev \ python-pip python-setuptools sqlite3 \ libssl-dev python-virtualenv libjpeg-dev libxslt1-dev Installing prerequisites on ArchLinux:: - sudo pacman -S base-devel python2 python-pip \ + sudo pacman -S base-devel python python-pip \ python-setuptools python-virtualenv sqlite3 Installing prerequisites on CentOS 7 or Fedora 25:: @@ -126,12 +126,9 @@ Installing prerequisites on Mac OS X:: Installing prerequisites on Raspbian:: - sudo apt-get install build-essential python2.7-dev libffi-dev \ + sudo apt-get install build-essential python3-dev libffi-dev \ python-pip python-setuptools sqlite3 \ libssl-dev python-virtualenv libjpeg-dev - sudo pip install --upgrade pip - sudo pip install --upgrade ndg-httpsclient - sudo pip install --upgrade virtualenv Installing prerequisites on openSUSE:: @@ -146,20 +143,21 @@ Installing prerequisites on OpenBSD:: To install the Synapse homeserver run:: - virtualenv -p python2.7 ~/.synapse - source ~/.synapse/bin/activate + mkdir -p ~/synapse + virtualenv -p python3 ~/synapse/env + source ~/synapse/env/bin/activate pip install --upgrade pip pip install --upgrade setuptools pip install matrix-synapse This installs Synapse, along with the libraries it uses, into a virtual -environment under ``~/.synapse``. Feel free to pick a different directory +environment under ``~/synapse/env``. Feel free to pick a different directory if you prefer. This Synapse installation can then be later upgraded by using pip again with the update flag:: - source ~/.synapse/bin/activate + source ~/synapse/env/bin/activate pip install -U matrix-synapse In case of problems, please see the _`Troubleshooting` section below. @@ -240,7 +238,7 @@ commandline script. To get started, it is easiest to use the command line to register new users:: - $ source ~/.synapse/bin/activate + $ source ~/synapse/env/bin/activate $ synctl start # if not already running $ register_new_matrix_user -c homeserver.yaml https://localhost:8448 New user localpart: erikj @@ -266,13 +264,12 @@ Running Synapse =============== To actually run your new homeserver, pick a working directory for Synapse to -run (e.g. ``~/.synapse``), and:: +run (e.g. ``~/synapse``), and:: - cd ~/.synapse - source ./bin/activate + cd ~/synapse + source env/bin/activate synctl start - Connecting to Synapse from a client =================================== @@ -380,35 +377,17 @@ the generated config), https://www.archlinux.org/packages/community/any/python2-matrix-angular-sdk/ will also need to be installed. -Alternatively, to install using pip a few changes may be needed as ArchLinux -defaults to python 3, but synapse currently assumes python 2.7 by default: - pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):: - sudo pip2.7 install --upgrade pip - -You also may need to explicitly specify python 2.7 again during the install -request:: - - pip2.7 install https://github.com/matrix-org/synapse/tarball/master + sudo pip install --upgrade pip If you encounter an error with lib bcrypt causing an Wrong ELF Class: ELFCLASS32 (x64 Systems), you may need to reinstall py-bcrypt to correctly compile it under the right architecture. (This should not be needed if installing under virtualenv):: - sudo pip2.7 uninstall py-bcrypt - sudo pip2.7 install py-bcrypt - -During setup of Synapse you need to call python2.7 directly again:: - - cd ~/.synapse - python2.7 -m synapse.app.homeserver \ - --server-name machine.my.domain.name \ - --config-path homeserver.yaml \ - --generate-config - -...substituting your host and domain name as appropriate. + sudo pip uninstall py-bcrypt + sudo pip install py-bcrypt FreeBSD ------- @@ -475,7 +454,7 @@ You can fix this by manually upgrading pip and virtualenv:: sudo pip install --upgrade virtualenv -You can next rerun ``virtualenv -p python2.7 synapse`` to update the virtual env. +You can next rerun ``virtualenv -p python3 synapse`` to update the virtual env. Installing may fail during installing virtualenv with ``InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning.`` You can fix this by manually installing ndg-httpsclient:: @@ -524,16 +503,6 @@ log lines and looking for any 'Processed request' lines which take more than a few seconds to execute. Please let us know at #matrix-dev:matrix.org if you see this failure mode so we can help debug it, however. -ArchLinux -~~~~~~~~~ - -If running `$ synctl start` fails with 'returned non-zero exit status 1', -you will need to explicitly call Python2.7 - either running as:: - - python2.7 -m synapse.app.homeserver --daemonize -c homeserver.yaml - -...or by editing synctl with the correct python executable. - Upgrading an existing Synapse ============================= @@ -731,7 +700,7 @@ port: * Until v0.33.3, Synapse did not support SNI on the federation port (`bug #1491 <https://github.com/matrix-org/synapse/issues/1491>`_). This bug - is now fixed, but means that federating with older servers can be unreliable + is now fixed, but means that federating with older servers can be unreliable when using name-based virtual hosting. Furthermore, a number of the normal reasons for using a reverse-proxy do not diff --git a/UPGRADE.rst b/UPGRADE.rst index aa5473ec62..9d68a64058 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -51,11 +51,70 @@ returned by the Client-Server API: Upgrading to v0.34.0 ==================== -This release removes the ``riot.im`` from the default list of trusted identity servers. +1. This release is the first to fully support Python 3. We recommend switching + to Python 3, as it has been shown to give performance improvements. + + For users who have installed Synapse into a virtualenv, we recommend doing + this by creating a new virtualenv. For example:: + + virtualenv -p python3 ~/synapse/env3 + source ~/synapse/env3/bin/activate + pip install matrix-synapse + + You can then start synapse as normal, having activated the new virtualenv:: + + cd ~/synapse + source env3/bin/activate + synctl start + + Users who have installed from distribution packages should see the relevant + package documentation. + + * When upgrading to Python 3, you **must** make sure that your log files are + configured as UTF-8, by adding ``encoding: utf8`` to the + ``RotatingFileHandler`` configuration (if you have one) in your + ``<server>.log.config`` file. For example, if your ``log.config`` file + contains:: + + handlers: + file: + class: logging.handlers.RotatingFileHandler + formatter: precise + filename: homeserver.log + maxBytes: 104857600 + backupCount: 10 + filters: [context] + console: + class: logging.StreamHandler + formatter: precise + filters: [context] + + Then you should update this to be:: + + handlers: + file: + class: logging.handlers.RotatingFileHandler + formatter: precise + filename: homeserver.log + maxBytes: 104857600 + backupCount: 10 + filters: [context] + encoding: utf8 + console: + class: logging.StreamHandler + formatter: precise + filters: [context] + + There is no need to revert this change if downgrading to Python 2. + +2. This release removes the ``riot.im`` from the default list of trusted + identity servers. + + If ``riot.im`` is in your homeserver's list of + ``trusted_third_party_id_servers``, you should remove it. It was added in + case a hypothetical future identity server was put there. If you don't + remove it, users may be unable to deactivate their accounts. -If ``riot.im`` is in your homeserver's list of ``trusted_third_party_id_servers``, -you should remove it. It was added in case a hypothetical future identity server was -put there. If you don't remove it, users may be unable to deactivate their accounts. Upgrading to v0.33.7 ==================== diff --git a/changelog.d/4260.misc b/changelog.d/4260.misc new file mode 100644 index 0000000000..0f7c4faf28 --- /dev/null +++ b/changelog.d/4260.misc @@ -0,0 +1 @@ +Update README.rst and UPGRADE.rst for Python 3. |