Switch to using a delta file

Add changelog
Switch INSERT + UPDATE to UPSERT
2019-11-19 10:49:40 +00:00 · 2019-11-18 17:50:08 +00:00 · 2019-11-18 17:47:41 +00:00
938 changed files with 32084 additions and 66492 deletions
@@ -0,0 +1,22 @@
 version: '3.1'
 services:
  postgres:
    image: postgres:9.5
    environment:
      POSTGRES_PASSWORD: postgres
    command: -c fsync=off
  testenv:
    image: python:3.5
    depends_on:
      - postgres
    env_file: .env
    environment:
      SYNAPSE_POSTGRES_HOST: postgres
      SYNAPSE_POSTGRES_USER: postgres
      SYNAPSE_POSTGRES_PASSWORD: postgres
    working_dir: /src
    volumes:
      - ..:/src
@@ -0,0 +1,22 @@
 version: '3.1'
 services:
  postgres:
    image: postgres:11
    environment:
      POSTGRES_PASSWORD: postgres
    command: -c fsync=off
  testenv:
    image: python:3.7
    depends_on:
      - postgres
    env_file: .env
    environment:
      SYNAPSE_POSTGRES_HOST: postgres
      SYNAPSE_POSTGRES_USER: postgres
      SYNAPSE_POSTGRES_PASSWORD: postgres
    working_dir: /src
    volumes:
      - ..:/src
@@ -0,0 +1,22 @@
 version: '3.1'
 services:
  postgres:
    image: postgres:9.5
    environment:
      POSTGRES_PASSWORD: postgres
    command: -c fsync=off
  testenv:
    image: python:3.7
    depends_on:
      - postgres
    env_file: .env
    environment:
      SYNAPSE_POSTGRES_HOST: postgres
      SYNAPSE_POSTGRES_USER: postgres
      SYNAPSE_POSTGRES_PASSWORD: postgres
    working_dir: /src
    volumes:
      - ..:/src
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-set -e
+set -ex
 if [[ "$BUILDKITE_BRANCH" =~ ^(develop|master|dinsic|shhs|release-.*)$ ]]; then
    echo "Not merging forward, as this is a release branch"
@@ -18,8 +18,6 @@ else
    GITBASE=$BUILDKITE_PULL_REQUEST_BASE_BRANCH
 fi
 echo "--- merge_base_branch $GITBASE"
 # Show what we are before
 git --no-pager show -s
@@ -1,7 +1,7 @@
 # Configuration file used for testing the 'synapse_port_db' script.
 # Tells the script to connect to the postgresql database that will be available in the
 # CI's Docker setup at the point where this file is considered.
-server_name: "localhost:8800"
+server_name: "test"
 signing_key_path: "/src/.buildkite/test.signing.key"
@@ -1,13 +0,0 @@
 #!/bin/bash
 # this script is run by buildkite in a plain `xenial` container; it installs the
 # minimal requirements for tox and hands over to the py35-old tox environment.
 set -ex
 apt-get update
 apt-get install -y python3.5 python3.5-dev python3-pip libxml2-dev libxslt-dev zlib1g-dev tox
 export LANG="C.UTF-8"
 exec tox -e py35-old,combine
@@ -1,7 +1,7 @@
 # Configuration file used for testing the 'synapse_port_db' script.
 # Tells the 'update_database' script to connect to the test SQLite database to upgrade its
 # schema and run background updates on it.
-server_name: "localhost:8800"
+server_name: "test"
 signing_key_path: "/src/.buildkite/test.signing.key"
@@ -5,6 +5,8 @@ Message history can be paginated
 Can re-join room if re-invited
 /upgrade creates a new room
 The only membership state included in an initial sync is for all the senders in the timeline
 Local device key changes get to remote servers
@@ -26,16 +28,3 @@ User sees updates to presence from other users in the incremental sync.
 Gapped incremental syncs include all state changes
 Old members are included in gappy incr LL sync if they start speaking
 # new failures as of https://github.com/matrix-org/sytest/pull/732
 Device list doesn't change if remote server is down
 Remote servers cannot set power levels in rooms without existing powerlevels
 Remote servers should reject attempts by non-creators to set the power levels
 # https://buildkite.com/matrix-dot-org/synapse/builds/6134#6f67bf47-e234-474d-80e8-c6e1868b15c5
 Server correctly handles incoming m.device_list_update
 # this fails reliably with a torture level of 100 due to https://github.com/matrix-org/synapse/issues/6536
 Outbound federation requests missing prev_events and then asks for /state_ids and resolves the state
 Can get rooms/{roomId}/members at a given point
@@ -4,16 +4,18 @@ jobs:
    machine: true
    steps:
      - checkout
-      - run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:${CIRCLE_TAG} .
+      - run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:${CIRCLE_TAG} -t matrixdotorg/synapse:${CIRCLE_TAG}-py3 .
      - run: docker login --username $DOCKER_HUB_USERNAME --password $DOCKER_HUB_PASSWORD
      - run: docker push matrixdotorg/synapse:${CIRCLE_TAG}
      - run: docker push matrixdotorg/synapse:${CIRCLE_TAG}-py3
  dockerhubuploadlatest:
    machine: true
    steps:
      - checkout
-      - run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:latest .
+      - run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:latest -t matrixdotorg/synapse:latest-py3 .
      - run: docker login --username $DOCKER_HUB_USERNAME --password $DOCKER_HUB_PASSWORD
      - run: docker push matrixdotorg/synapse:latest
      - run: docker push matrixdotorg/synapse:latest-py3
 workflows:
  version: 2
@@ -1,5 +0,0 @@
 **If you are looking for support** please ask in **#synapse:matrix.org**
 (using a matrix.org account if necessary). We do not use GitHub issues for
 support.
 **If you want to report a security issue** please see https://matrix.org/security-disclosure-policy/
@@ -6,11 +6,9 @@ about: Create a report to help us improve
 <!--
-**THIS IS NOT A SUPPORT CHANNEL!**
+**IF YOU HAVE SUPPORT QUESTIONS ABOUT RUNNING OR CONFIGURING YOUR OWN HOME SERVER**:
-**IF YOU HAVE SUPPORT QUESTIONS ABOUT RUNNING OR CONFIGURING YOUR OWN HOME SERVER**,
+You will likely get better support more quickly if you ask in ** #synapse:matrix.org ** ;)
 please ask in **#synapse:matrix.org** (using a matrix.org account if necessary)
 If you want to report a security issue, please see https://matrix.org/security-disclosure-policy/
 This is a bug report template. By following the instructions below and
 filling out the sections with your information, you will help the us to get all
@@ -1,12 +1,8 @@
 ### Pull Request Checklist
-<!-- Please read CONTRIBUTING.md before submitting your pull request -->
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
 * [ ] Pull request is based on the develop branch
-* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.md#changelog). The entry should:
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.rst#changelog)
-  - Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from `EventStore` to `EventWorkerStore`.".
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.rst#sign-off)
-  - Use markdown where necessary, mostly for `code blocks`.
+* [ ] Code style is correct (run the [linters](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.rst#code-style))
  - End with either a period (.) or an exclamation mark (!).
  - Start with a capital letter.
 * [ ] Pull request includes a [sign off](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.md#sign-off)
 * [ ] Code style is correct (run the [linters](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.md#code-style))
@@ -46,6 +46,3 @@ Joseph Weston <joseph at weston.cloud>
 Benjamin Saunders <ben.e.saunders at gmail dot com>
 * Documentation improvements
 Werner Sembach <werner.sembach at fau dot de>
 * Automatically remove a group/community when it is empty
@@ -1,268 +0,0 @@
 # Contributing code to Synapse
 Everyone is welcome to contribute code to [matrix.org
 projects](https://github.com/matrix-org), provided that they are willing to
 license their contributions under the same license as the project itself. We
 follow a simple 'inbound=outbound' model for contributions: the act of
 submitting an 'inbound' contribution means that the contributor agrees to
 license the code under the same terms as the project's overall 'outbound'
 license - in our case, this is almost always Apache Software License v2 (see
 [LICENSE](LICENSE)).
 ## How to contribute
 The preferred and easiest way to contribute changes is to fork the relevant
 project on github, and then [create a pull request](
 https://help.github.com/articles/using-pull-requests/) to ask us to pull your
 changes into our repo.
 Some other points to follow:
 * Please base your changes on the `develop` branch.
 * Please follow the [code style requirements](#code-style).
 * Please include a [changelog entry](#changelog) with each PR.
 * Please [sign off](#sign-off) your contribution.
 * Please keep an eye on the pull request for feedback from the [continuous
   integration system](#continuous-integration-and-testing) and try to fix any
   errors that come up.
 * If you need to [update your PR](#updating-your-pull-request), just add new
   commits to your branch rather than rebasing.
 ## Code style
 Synapse's code style is documented [here](docs/code_style.md). Please follow
 it, including the conventions for the [sample configuration
 file](docs/code_style.md#configuration-file-format).
 Many of the conventions are enforced by scripts which are run as part of the
 [continuous integration system](#continuous-integration-and-testing). To help
 check if you have followed the code style, you can run `scripts-dev/lint.sh`
 locally. You'll need python 3.6 or later, and to install a number of tools:
 ```
 # Install the dependencies
 pip install -U black flake8 flake8-comprehensions isort
 # Run the linter script
 ./scripts-dev/lint.sh
 ```
 **Note that the script does not just test/check, but also reformats code, so you
 may wish to ensure any new code is committed first**.
 By default, this script checks all files and can take some time; if you alter
 only certain files, you might wish to specify paths as arguments to reduce the
 run-time:
 ```
 ./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
 ```
 Before pushing new changes, ensure they don't produce linting errors. Commit any
 files that were corrected.
 Please ensure your changes match the cosmetic style of the existing project,
 and **never** mix cosmetic and functional changes in the same commit, as it
 makes it horribly hard to review otherwise.
 ## Changelog
 All changes, even minor ones, need a corresponding changelog / newsfragment
 entry. These are managed by [Towncrier](https://github.com/hawkowl/towncrier).
 To create a changelog entry, make a new file in the `changelog.d` directory named
 in the format of `PRnumber.type`. The type can be one of the following:
 * `feature`
 * `bugfix`
 * `docker` (for updates to the Docker image)
 * `doc` (for updates to the documentation)
 * `removal` (also used for deprecations)
 * `misc` (for internal-only changes)
 This file will become part of our [changelog](
 https://github.com/matrix-org/synapse/blob/master/CHANGES.md) at the next
 release, so the content of the file should be a short description of your
 change in the same style as the rest of the changelog. The file can contain Markdown
 formatting, and should end with a full stop (.) or an exclamation mark (!) for
 consistency.
 Adding credits to the changelog is encouraged, we value your
 contributions and would like to have you shouted out in the release notes!
 For example, a fix in PR #1234 would have its changelog entry in
 `changelog.d/1234.bugfix`, and contain content like:
 > The security levels of Florbs are now validated when received
 > via the `/federation/florb` endpoint. Contributed by Jane Matrix.
 If there are multiple pull requests involved in a single bugfix/feature/etc,
 then the content for each `changelog.d` file should be the same. Towncrier will
 merge the matching files together into a single changelog entry when we come to
 release.
 ### How do I know what to call the changelog file before I create the PR?
 Obviously, you don't know if you should call your newsfile
 `1234.bugfix` or `5678.bugfix` until you create the PR, which leads to a
 chicken-and-egg problem.
 There are two options for solving this:
 1. Open the PR without a changelog file, see what number you got, and *then*
    add the changelog file to your branch (see [Updating your pull
    request](#updating-your-pull-request)), or:
 1. Look at the [list of all
    issues/PRs](https://github.com/matrix-org/synapse/issues?q=), add one to the
    highest number you see, and quickly open the PR before somebody else claims
    your number.
    [This
    script](https://github.com/richvdh/scripts/blob/master/next_github_number.sh)
    might be helpful if you find yourself doing this a lot.
 Sorry, we know it's a bit fiddly, but it's *really* helpful for us when we come
 to put together a release!
 ### Debian changelog
 Changes which affect the debian packaging files (in `debian`) are an
 exception to the rule that all changes require a `changelog.d` file.
 In this case, you will need to add an entry to the debian changelog for the
 next release. For this, run the following command:
 ```
 dch
 ```
 This will make up a new version number (if there isn't already an unreleased
 version in flight), and open an editor where you can add a new changelog entry.
 (Our release process will ensure that the version number and maintainer name is
 corrected for the release.)
 If your change affects both the debian packaging *and* files outside the debian
 directory, you will need both a regular newsfragment *and* an entry in the
 debian changelog. (Though typically such changes should be submitted as two
 separate pull requests.)
 ## Sign off
 In order to have a concrete record that your contribution is intentional
 and you agree to license it under the same terms as the project's license, we've adopted the
 same lightweight approach that the Linux Kernel
 [submitting patches process](
 https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>),
 [Docker](https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
 projects use: the DCO (Developer Certificate of Origin:
 http://developercertificate.org/). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix:
 ```
 Developer Certificate of Origin
 Version 1.1
 Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
 660 York Street, Suite 102,
 San Francisco, CA 94110 USA
 Everyone is permitted to copy and distribute verbatim copies of this
 license document, but changing it is not allowed.
 Developer's Certificate of Origin 1.1
 By making a contribution to this project, I certify that:
 (a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or
 (b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or
 (c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.
 (d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
 ```
 If you agree to this for your contribution, then all that's needed is to
 include the line in your commit or pull request comment:
 ```
 Signed-off-by: Your Name <your@email.example.org>
 ```
 We accept contributions under a legally identifiable name, such as
 your name on government documentation or common-law names (names
 claimed by legitimate usage or repute). Unfortunately, we cannot
 accept anonymous contributions at this time.
 Git allows you to add this signoff automatically when using the `-s`
 flag to `git commit`, which uses the name and email set in your
 `user.name` and `user.email` git configs.
 ## Continuous integration and testing
 [Buildkite](https://buildkite.com/matrix-dot-org/synapse) will automatically
 run a series of checks and tests against any PR which is opened against the
 project; if your change breaks the build, this will be shown in GitHub, with
 links to the build results. If your build fails, please try to fix the errors
 and update your branch.
 To run unit tests in a local development environment, you can use:
 - ``tox -e py35`` (requires tox to be installed by ``pip install tox``)
  for SQLite-backed Synapse on Python 3.5.
 - ``tox -e py36`` for SQLite-backed Synapse on Python 3.6.
 - ``tox -e py36-postgres`` for PostgreSQL-backed Synapse on Python 3.6
  (requires a running local PostgreSQL with access to create databases).
 - ``./test_postgresql.sh`` for PostgreSQL-backed Synapse on Python 3.5
  (requires Docker). Entirely self-contained, recommended if you don't want to
  set up PostgreSQL yourself.
 Docker images are available for running the integration tests (SyTest) locally,
 see the [documentation in the SyTest repo](
 https://github.com/matrix-org/sytest/blob/develop/docker/README.md) for more
 information.
 ## Updating your pull request
 If you decide to make changes to your pull request - perhaps to address issues
 raised in a review, or to fix problems highlighted by [continuous
 integration](#continuous-integration-and-testing) - just add new commits to your
 branch, and push to GitHub. The pull request will automatically be updated.
 Please **avoid** rebasing your branch, especially once the PR has been
 reviewed: doing so makes it very difficult for a reviewer to see what has
 changed since a previous review.
 ## Notes for maintainers on merging PRs etc
 There are some notes for those with commit access to the project on how we
 manage git [here](docs/dev/git.md).
 ## Conclusion
 That's it! Matrix is a very open and collaborative project as you might expect
 given our obsession with open communication. If we're going to successfully
 matrix together all the fragmented communication technologies out there we are
 reliant on contributions and collaboration from the community to do so. So
 please get involved - and we hope you have as much fun hacking on Matrix as we
 do!
@@ -0,0 +1,206 @@
 Contributing code to Matrix
 ===========================
 Everyone is welcome to contribute code to Matrix
 (https://github.com/matrix-org), provided that they are willing to license
 their contributions under the same license as the project itself. We follow a
 simple 'inbound=outbound' model for contributions: the act of submitting an
 'inbound' contribution means that the contributor agrees to license the code
 under the same terms as the project's overall 'outbound' license - in our
 case, this is almost always Apache Software License v2 (see LICENSE).
 How to contribute
 ~~~~~~~~~~~~~~~~~
 The preferred and easiest way to contribute changes to Matrix is to fork the
 relevant project on github, and then create a pull request to ask us to pull
 your changes into our repo
 (https://help.github.com/articles/using-pull-requests/)
 **The single biggest thing you need to know is: please base your changes on
 the develop branch - /not/ master.**
 We use the master branch to track the most recent release, so that folks who
 blindly clone the repo and automatically check out master get something that
 works. Develop is the unstable branch where all the development actually
 happens: the workflow is that contributors should fork the develop branch to
 make a 'feature' branch for a particular contribution, and then make a pull
 request to merge this back into the matrix.org 'official' develop branch. We
 use github's pull request workflow to review the contribution, and either ask
 you to make any refinements needed or merge it and make them ourselves. The
 changes will then land on master when we next do a release.
 We use `Buildkite <https://buildkite.com/matrix-dot-org/synapse>`_ for
 continuous integration.  Buildkite builds need to be authorised by a
 maintainer. If your change breaks the build, this will be shown in GitHub, so
 please keep an eye on the pull request for feedback.
 To run unit tests in a local development environment, you can use:
 - ``tox -e py35`` (requires tox to be installed by ``pip install tox``)
  for SQLite-backed Synapse on Python 3.5.
 - ``tox -e py36`` for SQLite-backed Synapse on Python 3.6.
 - ``tox -e py36-postgres`` for PostgreSQL-backed Synapse on Python 3.6
  (requires a running local PostgreSQL with access to create databases).
 - ``./test_postgresql.sh`` for PostgreSQL-backed Synapse on Python 3.5
  (requires Docker). Entirely self-contained, recommended if you don't want to
  set up PostgreSQL yourself.
 Docker images are available for running the integration tests (SyTest) locally,
 see the `documentation in the SyTest repo
 <https://github.com/matrix-org/sytest/blob/develop/docker/README.md>`_ for more
 information.
 Code style
 ~~~~~~~~~~
 All Matrix projects have a well-defined code-style - and sometimes we've even
 got as far as documenting it... For instance, synapse's code style doc lives
 at https://github.com/matrix-org/synapse/tree/master/docs/code_style.md.
 To facilitate meeting these criteria you can run ``scripts-dev/lint.sh``
 locally. Since this runs the tools listed in the above document, you'll need
 python 3.6 and to install each tool. **Note that the script does not just
 test/check, but also reformats code, so you may wish to ensure any new code is
 committed first**. By default this script checks all files and can take some
 time; if you alter only certain files, you might wish to specify paths as
 arguments to reduce the run-time.
 Please ensure your changes match the cosmetic style of the existing project,
 and **never** mix cosmetic and functional changes in the same commit, as it
 makes it horribly hard to review otherwise.
 Before doing a commit, ensure the changes you've made don't produce
 linting errors. You can do this by running the linters as follows. Ensure to
 commit any files that were corrected.
 ::
    # Install the dependencies
    pip install -U black flake8 isort
    # Run the linter script
    ./scripts-dev/lint.sh
 Changelog
 ~~~~~~~~~
 All changes, even minor ones, need a corresponding changelog / newsfragment
 entry. These are managed by Towncrier
 (https://github.com/hawkowl/towncrier).
 To create a changelog entry, make a new file in the ``changelog.d`` file named
 in the format of ``PRnumber.type``. The type can be one of the following:
 * ``feature``.
 * ``bugfix``.
 * ``docker`` (for updates to the Docker image).
 * ``doc`` (for updates to the documentation).
 * ``removal`` (also used for deprecations).
 * ``misc`` (for internal-only changes).
 The content of the file is your changelog entry, which should be a short
 description of your change in the same style as the rest of our `changelog
 <https://github.com/matrix-org/synapse/blob/master/CHANGES.md>`_. The file can
 contain Markdown formatting, and should end with a full stop ('.') for
 consistency.
 Adding credits to the changelog is encouraged, we value your
 contributions and would like to have you shouted out in the release notes!
 For example, a fix in PR #1234 would have its changelog entry in
 ``changelog.d/1234.bugfix``, and contain content like "The security levels of
 Florbs are now validated when recieved over federation. Contributed by Jane
 Matrix.".
 Debian changelog
 ----------------
 Changes which affect the debian packaging files (in ``debian``) are an
 exception.
 In this case, you will need to add an entry to the debian changelog for the
 next release. For this, run the following command::
  dch
 This will make up a new version number (if there isn't already an unreleased
 version in flight), and open an editor where you can add a new changelog entry.
 (Our release process will ensure that the version number and maintainer name is
 corrected for the release.)
 If your change affects both the debian packaging *and* files outside the debian
 directory, you will need both a regular newsfragment *and* an entry in the
 debian changelog. (Though typically such changes should be submitted as two
 separate pull requests.)
 Sign off
 ~~~~~~~~
 In order to have a concrete record that your contribution is intentional
 and you agree to license it under the same terms as the project's license, we've adopted the
 same lightweight approach that the Linux Kernel
 `submitting patches process <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`_, Docker
 (https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
 projects use: the DCO (Developer Certificate of Origin:
 http://developercertificate.org/). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix::
    Developer Certificate of Origin
    Version 1.1
    Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
    660 York Street, Suite 102,
    San Francisco, CA 94110 USA
    Everyone is permitted to copy and distribute verbatim copies of this
    license document, but changing it is not allowed.
    Developer's Certificate of Origin 1.1
    By making a contribution to this project, I certify that:
    (a) The contribution was created in whole or in part by me and I
        have the right to submit it under the open source license
        indicated in the file; or
    (b) The contribution is based upon previous work that, to the best
        of my knowledge, is covered under an appropriate open source
        license and I have the right under that license to submit that
        work with modifications, whether created in whole or in part
        by me, under the same open source license (unless I am
        permitted to submit under a different license), as indicated
        in the file; or
    (c) The contribution was provided directly to me by some other
        person who certified (a), (b) or (c) and I have not modified
        it.
    (d) I understand and agree that this project and the contribution
        are public and that a record of the contribution (including all
        personal information I submit with it, including my sign-off) is
        maintained indefinitely and may be redistributed consistent with
        this project or the open source license(s) involved.
 If you agree to this for your contribution, then all that's needed is to
 include the line in your commit or pull request comment::
    Signed-off-by: Your Name <your@email.example.org>
 We accept contributions under a legally identifiable name, such as
 your name on government documentation or common-law names (names
 claimed by legitimate usage or repute). Unfortunately, we cannot
 accept anonymous contributions at this time.
 Git allows you to add this signoff automatically when using the ``-s``
 flag to ``git commit``, which uses the name and email set in your
 ``user.name`` and ``user.email`` git configs.
 Conclusion
 ~~~~~~~~~~
 That's it!  Matrix is a very open and collaborative project as you might expect
 given our obsession with open communication.  If we're going to successfully
 matrix together all the fragmented communication technologies out there we are
 reliant on contributions and collaboration from the community to do so.  So
 please get involved - and we hope you have as much fun hacking on Matrix as we
 do!
@@ -1,17 +1,15 @@
 - [Choosing your server name](#choosing-your-server-name)
 - [Picking a database engine](#picking-a-database-engine)
 - [Installing Synapse](#installing-synapse)
  - [Installing from source](#installing-from-source)
    - [Platform-Specific Instructions](#platform-specific-instructions)
    - [Troubleshooting Installation](#troubleshooting-installation)
  - [Prebuilt packages](#prebuilt-packages)
 - [Setting up Synapse](#setting-up-synapse)
  - [TLS certificates](#tls-certificates)
  - [Client Well-Known URI](#client-well-known-uri)
  - [Email](#email)
  - [Registering a user](#registering-a-user)
  - [Setting up a TURN server](#setting-up-a-turn-server)
  - [URL previews](#url-previews)
 - [Troubleshooting Installation](#troubleshooting-installation)
 # Choosing your server name
@@ -29,25 +27,6 @@ that your email address is probably `user@example.com` rather than
 `user@email.example.com`) - but doing so may require more advanced setup: see
 [Setting up Federation](docs/federate.md).
 # Picking a database engine
 Synapse offers two database engines:
 * [PostgreSQL](https://www.postgresql.org)
 * [SQLite](https://sqlite.org/)
 Almost all installations should opt to use PostgreSQL. Advantages include:
 * significant performance improvements due to the superior threading and
  caching model, smarter query optimiser
 * allowing the DB to be run on separate hardware
 For information on how to install and use PostgreSQL, please see
 [docs/postgres.md](docs/postgres.md)
 By default Synapse uses SQLite and in doing so trades performance for convenience.
 SQLite is only recommended in Synapse for testing purposes or for servers with
 light workloads.
 # Installing Synapse
 ## Installing from source
@@ -57,7 +36,7 @@ light workloads.
 System requirements:
 - POSIX-compliant system (tested on Linux & OS X)
- Python 3.5.2 or later, up to Python 3.8.
+- Python 3.5, 3.6, 3.7 or 3.8.
 - At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org
 Synapse is written in Python but some of the libraries it uses are written in
@@ -91,7 +70,7 @@ pip install -U matrix-synapse
 ```
 Before you can start Synapse, you will need to generate a configuration
-file. To do this, run (in your virtualenv, as before):
+file. To do this, run (in your virtualenv, as before)::
 ```
 cd ~/synapse
@@ -105,24 +84,22 @@ python -m synapse.app.homeserver \
 ... substituting an appropriate value for `--server-name`.
 This command will generate you a config file that you can then customise, but it will
-also generate a set of keys for you. These keys will allow your homeserver to
+also generate a set of keys for you. These keys will allow your Home Server to
-identify itself to other homeserver, so don't lose or delete them. It would be
+identify itself to other Home Servers, so don't lose or delete them. It would be
 wise to back them up somewhere safe. (If, for whatever reason, you do need to
-change your homeserver's keys, you may find that other homeserver have the
+change your Home Server's keys, you may find that other Home Servers have the
 old key cached. If you update the signing key, you should change the name of the
 key in the `<server name>.signing.key` file (the second word) to something
 different. See the
 [spec](https://matrix.org/docs/spec/server_server/latest.html#retrieving-server-keys)
-for more information on key management).
+for more information on key management.)
 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
-cd ~/synapse
+    source env/bin/activate
-source env/bin/activate
+    synctl start
 synctl start
 ```
 ### Platform-Specific Instructions
@@ -132,8 +109,8 @@ Installing prerequisites on Ubuntu or Debian:
 ```
 sudo apt-get install build-essential python3-dev libffi-dev \
-                     python3-pip python3-setuptools sqlite3 \
+                     python-pip python-setuptools sqlite3 \
-                     libssl-dev virtualenv libjpeg-dev libxslt1-dev
+                     libssl-dev python-virtualenv libjpeg-dev libxslt1-dev
 ```
 #### ArchLinux
@@ -147,32 +124,18 @@ sudo pacman -S base-devel python python-pip \
 #### CentOS/Fedora
-Installing prerequisites on CentOS 8 or Fedora>26:
+Installing prerequisites on CentOS 7 or Fedora 25:
 ```
 sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
                 libwebp-devel tk-devel redhat-rpm-config \
                 python3-virtualenv libffi-devel openssl-devel
 sudo dnf groupinstall "Development Tools"
 ```
 Installing prerequisites on CentOS 7 or Fedora<=25:
 ```
 sudo yum install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
                 lcms2-devel libwebp-devel tcl-devel tk-devel redhat-rpm-config \
-                 python3-virtualenv libffi-devel openssl-devel
+                 python-virtualenv libffi-devel openssl-devel
 sudo yum groupinstall "Development Tools"
 ```
-Note that Synapse does not support versions of SQLite before 3.11, and CentOS 7
+#### Mac OS X
 uses SQLite 3.7. You may be able to work around this by installing a more
 recent SQLite version, but it is recommended that you instead use a Postgres
 database: see [docs/postgres.md](docs/postgres.md).
-#### macOS
+Installing prerequisites on Mac OS X:
 Installing prerequisites on macOS:
 ```
 xcode-select --install
@@ -181,14 +144,6 @@ sudo pip install virtualenv
 brew install pkg-config libffi
 ```
 On macOS Catalina (10.15) you may need to explicitly install OpenSSL
 via brew and inform `pip` about it so that `psycopg2` builds:
 ```
 brew install openssl@1.1
 export LDFLAGS=-L/usr/local/Cellar/openssl\@1.1/1.1.1d/lib/
 ```
 #### OpenSUSE
 Installing prerequisites on openSUSE:
@@ -201,41 +156,35 @@ sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \
 #### OpenBSD
-A port of Synapse is available under `net/synapse`. The filesystem
+Installing prerequisites on OpenBSD:
 underlying the homeserver directory (defaults to `/var/synapse`) has to be
 mounted with `wxallowed` (cf. `mount(8)`), so creating a separate filesystem
 and mounting it to `/var/synapse` should be taken into consideration.
 To be able to build Synapse's dependency on python the `WRKOBJDIR`
 (cf. `bsd.port.mk(5)`) for building python, too, needs to be on a filesystem
 mounted with `wxallowed` (cf. `mount(8)`).
 Creating a `WRKOBJDIR` for building python under `/usr/local` (which on a
 default OpenBSD installation is mounted with `wxallowed`):
 ```
-doas mkdir /usr/local/pobj_wxallowed
+doas pkg_add python libffi py-pip py-setuptools sqlite3 py-virtualenv \
              libxslt jpeg
 ```
-Assuming `PORTS_PRIVSEP=Yes` (cf. `bsd.port.mk(5)`) and `SUDO=doas` are
+There is currently no port for OpenBSD. Additionally, OpenBSD's security
-configured in `/etc/mk.conf`:
+settings require a slightly more difficult installation process.
-```
+XXX: I suspect this is out of date.
 doas chown _pbuild:_pbuild /usr/local/pobj_wxallowed
 ```
-Setting the `WRKOBJDIR` for building python:
+1. Create a new directory in `/usr/local` called `_synapse`. Also, create a
   new user called `_synapse` and set that directory as the new user's home.
   This is required because, by default, OpenBSD only allows binaries which need
   write and execute permissions on the same memory space to be run from
   `/usr/local`.
 2. `su` to the new `_synapse` user and change to their home directory.
 3. Create a new virtualenv: `virtualenv -p python2.7 ~/.synapse`
 4. Source the virtualenv configuration located at
   `/usr/local/_synapse/.synapse/bin/activate`. This is done in `ksh` by
   using the `.` command, rather than `bash`'s `source`.
 5. Optionally, use `pip` to install `lxml`, which Synapse needs to parse
   webpages for their titles.
 6. Use `pip` to install this repository: `pip install matrix-synapse`
 7. Optionally, change `_synapse`'s shell to `/bin/false` to reduce the
   chance of a compromised Synapse server being used to take over your box.
-```
+After this, you may proceed with the rest of the install directions.
 echo WRKOBJDIR_lang/python/3.7=/usr/local/pobj_wxallowed  \\nWRKOBJDIR_lang/python/2.7=/usr/local/pobj_wxallowed >> /etc/mk.conf
 ```
 Building Synapse:
 ```
 cd /usr/ports/net/synapse
 make install
 ```
 #### Windows
@@ -246,6 +195,45 @@ be found at https://docs.microsoft.com/en-us/windows/wsl/install-win10 for
 Windows 10 and https://docs.microsoft.com/en-us/windows/wsl/install-on-server
 for Windows Server.
 ### Troubleshooting Installation
 XXX a bunch of this is no longer relevant.
 Synapse requires pip 8 or later, so if your OS provides too old a version you
 may need to manually upgrade it::
    sudo pip install --upgrade pip
 Installing may fail with `Could not find any downloads that satisfy the requirement pymacaroons-pynacl (from matrix-synapse==0.12.0)`.
 You can fix this by manually upgrading pip and virtualenv::
    sudo pip install --upgrade virtualenv
 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::
    pip install --upgrade ndg-httpsclient
 Installing may fail with `mock requires setuptools>=17.1. Aborting installation`.
 You can fix this by upgrading setuptools::
    pip install --upgrade setuptools
 If pip crashes mid-installation for reason (e.g. lost terminal), pip may
 refuse to run until you remove the temporary installation directory it
 created. To reset the installation::
    rm -rf /tmp/pip_install_matrix
 pip seems to leak *lots* of memory during installation.  For instance, a Linux
 host with 512MB of RAM may run out of memory whilst installing Twisted.  If this
 happens, you will have to individually install the dependencies which are
 failing, e.g.::
    pip install twisted
 ## Prebuilt packages
 As an alternative to installing from source, prebuilt packages are available
@@ -255,9 +243,9 @@ for a number of platforms.
 There is an offical synapse image available at
 https://hub.docker.com/r/matrixdotorg/synapse which can be used with
-the docker-compose file available at [contrib/docker](contrib/docker). Further
+the docker-compose file available at [contrib/docker](contrib/docker). Further information on
-information on this including configuration options is available in the README
+this including configuration options is available in the README on
-on hub.docker.com.
+hub.docker.com.
 Alternatively, Andreas Peters (previously Silvio Fricke) has contributed a
 Dockerfile to automate a synapse server in a single Docker image, at
@@ -265,8 +253,7 @@ https://hub.docker.com/r/avhost/docker-matrix/tags/
 Slavi Pantaleev has created an Ansible playbook,
 which installs the offical Docker image of Matrix Synapse
-along with many other Matrix-related services (Postgres database, Element, coturn,
+along with many other Matrix-related services (Postgres database, riot-web, coturn, mxisd, SSL support, etc.).
 ma1sd, SSL support, etc.).
 For more details, see
 https://github.com/spantaleev/matrix-docker-ansible-deploy
@@ -299,27 +286,22 @@ The fingerprint of the repository signing key (as shown by `gpg
 /usr/share/keyrings/matrix-org-archive-keyring.gpg`) is
 `AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058`.
-#### Downstream Debian packages
+#### Downstream Debian/Ubuntu packages
-We do not recommend using the packages from the default Debian `buster`
+For `buster` and `sid`, Synapse is available in the Debian repositories and
-repository at this time, as they are old and suffer from known security
+it should be possible to install it with simply:
 vulnerabilities. You can install the latest version of Synapse from
 [our repository](#matrixorg-packages) or from `buster-backports`. Please
 see the [Debian documentation](https://backports.debian.org/Instructions/)
 for information on how to use backports.
 If you are using Debian `sid` or testing, Synapse is available in the default
 repositories and it should be possible to install it simply with:
 ```
-sudo apt install matrix-synapse
+    sudo apt install matrix-synapse
 ```
-#### Downstream Ubuntu packages
+There is also a version of `matrix-synapse` in `stretch-backports`. Please see
 the [Debian documentation on
 backports](https://backports.debian.org/Instructions/) for information on how
 to use them.
-We do not recommend using the packages in the default Ubuntu repository
+We do not recommend using the packages in downstream Ubuntu at this time, as
-at this time, as they are old and suffer from known security vulnerabilities.
+they are old and suffer from known security vulnerabilities.
 The latest version of Synapse can be installed from [our repository](#matrixorg-packages).
 ### Fedora
@@ -371,30 +353,16 @@ sudo pip install py-bcrypt
 Synapse can be found in the void repositories as 'synapse':
-```
+    xbps-install -Su
-xbps-install -Su
+    xbps-install -S synapse
 xbps-install -S synapse
 ```
 ### FreeBSD
 Synapse can be installed via FreeBSD Ports or Packages contributed by Brendan Molloy from:
 - Ports: `cd /usr/ports/net-im/py-matrix-synapse && make install clean`
- - Packages: `pkg install py37-matrix-synapse`
+ - Packages: `pkg install py27-matrix-synapse`
 ### OpenBSD
 As of OpenBSD 6.7 Synapse is available as a pre-compiled binary. The filesystem
 underlying the homeserver directory (defaults to `/var/synapse`) has to be
 mounted with `wxallowed` (cf. `mount(8)`), so creating a separate filesystem
 and mounting it to `/var/synapse` should be taken into consideration.
 Installing Synapse:
 ```
 doas pkg_add synapse
 ```
 ### NixOS
@@ -407,17 +375,15 @@ Once you have installed synapse as above, you will need to configure it.
 ## TLS certificates
-The default configuration exposes a single HTTP port on the local
+The default configuration exposes a single HTTP port: http://localhost:8008. It
-interface: `http://localhost:8008`. It is suitable for local testing,
+is suitable for local testing, but for any practical use, you will either need
-but for any practical use, you will need Synapse's APIs to be served
+to enable a reverse proxy, or configure Synapse to expose an HTTPS port.
 over HTTPS.
-The recommended way to do so is to set up a reverse proxy on port
+For information on using a reverse proxy, see
 `8448`. You can find documentation on doing so in
 [docs/reverse_proxy.md](docs/reverse_proxy.md).
-Alternatively, you can configure Synapse to expose an HTTPS port. To do
+To configure Synapse to expose an HTTPS port, you will need to edit
-so, you will need to edit `homeserver.yaml`, as follows:
+`homeserver.yaml`, as follows:
 * First, under the `listeners` section, uncomment the configuration for the
  TLS-enabled listener. (Remove the hash sign (`#`) at the start of
@@ -430,76 +396,20 @@ so, you will need to edit `homeserver.yaml`, as follows:
      resources:
        - names: [client, federation]
  ```
 * You will also need to uncomment the `tls_certificate_path` and
-  `tls_private_key_path` lines under the `TLS` section. You will need to manage
+  `tls_private_key_path` lines under the `TLS` section. You can either
-  provisioning of these certificates yourself — Synapse had built-in ACME
+  point these settings at an existing certificate and key, or you can
-  support, but the ACMEv1 protocol Synapse implements is deprecated, not
+  enable Synapse's built-in ACME (Let's Encrypt) support. Instructions
-  allowed by LetsEncrypt for new sites, and will break for existing sites in
+  for having Synapse automatically provision and renew federation
-  late 2020. See [ACME.md](docs/ACME.md).
+  certificates through ACME can be found at [ACME.md](docs/ACME.md). If you
-
+  are using your own certificate, be sure to use a `.pem` file that includes
-  If you are using your own certificate, be sure to use a `.pem` file that
+  the full certificate chain including any intermediate certificates (for
-  includes the full certificate chain including any intermediate certificates
+  instance, if using certbot, use `fullchain.pem` as your certificate, not
  (for instance, if using certbot, use `fullchain.pem` as your certificate, not
  `cert.pem`).
 For a more detailed guide to configuring your server for federation, see
-[federate.md](docs/federate.md).
+[federate.md](docs/federate.md)
 ## Client Well-Known URI
 Setting up the client Well-Known URI is optional but if you set it up, it will
 allow users to enter their full username (e.g. `@user:<server_name>`) into clients
 which support well-known lookup to automatically configure the homeserver and
 identity server URLs. This is useful so that users don't have to memorize or think
 about the actual homeserver URL you are using.
 The URL `https://<server_name>/.well-known/matrix/client` should return JSON in
 the following format.
 ```
 {
  "m.homeserver": {
    "base_url": "https://<matrix.example.com>"
  }
 }
 ```
 It can optionally contain identity server information as well.
 ```
 {
  "m.homeserver": {
    "base_url": "https://<matrix.example.com>"
  },
  "m.identity_server": {
    "base_url": "https://<identity.example.com>"
  }
 }
 ```
 To work in browser based clients, the file must be served with the appropriate
 Cross-Origin Resource Sharing (CORS) headers. A recommended value would be
 `Access-Control-Allow-Origin: *` which would allow all browser based clients to
 view it.
 In nginx this would be something like:
 ```
 location /.well-known/matrix/client {
    return 200 '{"m.homeserver": {"base_url": "https://<matrix.example.com>"}}';
    add_header Content-Type application/json;
    add_header Access-Control-Allow-Origin *;
 }
 ```
 You should also ensure the `public_baseurl` option in `homeserver.yaml` is set
 correctly. `public_baseurl` should be set to the URL that clients will use to
 connect to your server. This is the same URL you put for the `m.homeserver`
 `base_url` above.
 ```
 public_baseurl: "https://<matrix.example.com>"
 ```
 ## Email
@@ -518,7 +428,7 @@ email will be disabled.
 ## Registering a user
-The easiest way to create a new user is to do so from a client like [Element](https://element.io/).
+The easiest way to create a new user is to do so from a client like [Riot](https://riot.im).
 Alternatively you can do so from the command line if you have installed via pip.
@@ -545,7 +455,7 @@ on your server even if `enable_registration` is `false`.
 ## Setting up a TURN server
 For reliable VoIP calls to be routed via this homeserver, you MUST configure
-a TURN server. See [docs/turn-howto.md](docs/turn-howto.md) for details.
+a TURN server.  See [docs/turn-howto.md](docs/turn-howto.md) for details.
 ## URL previews
@@ -554,24 +464,10 @@ turn it on you must enable the `url_preview_enabled: True` config parameter
 and explicitly specify the IP ranges that Synapse is not allowed to spider for
 previewing in the `url_preview_ip_range_blacklist` configuration parameter.
 This is critical from a security perspective to stop arbitrary Matrix users
-spidering 'internal' URLs on your network. At the very least we recommend that
+spidering 'internal' URLs on your network.  At the very least we recommend that
 your loopback and RFC1918 IP addresses are blacklisted.
-This also requires the optional `lxml` and `netaddr` python dependencies to be
+This also requires the optional lxml and netaddr python dependencies to be
-installed. This in turn requires the `libxml2` library to be available - on
+installed.  This in turn requires the libxml2 library to be available - on
 Debian/Ubuntu this means `apt-get install libxml2-dev`, or equivalent for
 your OS.
 # Troubleshooting Installation
 `pip` seems to leak *lots* of memory during installation. For instance, a Linux
 host with 512MB of RAM may run out of memory whilst installing Twisted. If this
 happens, you will have to individually install the dependencies which are
 failing, e.g.:
 ```
 pip install twisted
 ```
 If you have any other problems, feel free to ask in
 [#synapse:matrix.org](https://matrix.to/#/#synapse:matrix.org).
@@ -30,24 +30,23 @@ recursive-include synapse/static *.gif
 recursive-include synapse/static *.html
 recursive-include synapse/static *.js
 exclude .codecov.yml
 exclude .coveragerc
 exclude .dockerignore
 exclude .editorconfig
 exclude Dockerfile
-exclude mypy.ini
+exclude .dockerignore
 exclude sytest-blacklist
 exclude test_postgresql.sh
 exclude .editorconfig
 exclude sytest-blacklist
 include pyproject.toml
 recursive-include changelog.d *
 prune .buildkite
 prune .circleci
 prune .codecov.yml
 prune .coveragerc
 prune .github
 prune contrib
 prune debian
 prune demo/etc
 prune docker
 prune mypy.ini
 prune snap
 prune stubs
@@ -1,11 +1,3 @@
 ================
 Synapse |shield|
 ================
 .. |shield| image:: https://img.shields.io/matrix/synapse:matrix.org?label=support&logo=matrix
  :alt: (get support on #synapse:matrix.org)
  :target: https://matrix.to/#/#synapse:matrix.org
 .. contents::
 Introduction
@@ -45,7 +37,7 @@ which handle:
 - Eventually-consistent cryptographically secure synchronisation of room
  state across a global open network of federated servers and services
 - Sending and receiving extensible messages in a room with (optional)
-  end-to-end encryption
+  end-to-end encryption[1]
 - Inviting, joining, leaving, kicking, banning room members
 - Managing user accounts (registration, login, logout)
 - Using 3rd Party IDs (3PIDs) such as email addresses, phone numbers,
@@ -82,15 +74,7 @@ at the `Matrix spec <https://matrix.org/docs/spec>`_, and experiment with the
 Thanks for using Matrix!
-Support
+[1] End-to-end encryption is currently in beta: `blog post <https://matrix.org/blog/2016/11/21/matrixs-olm-end-to-end-encryption-security-assessment-released-and-implemented-cross-platform-on-riot-at-last>`_.
 =======
 For support installing or managing Synapse, please join |room|_ (from a matrix.org
 account if necessary) and ask questions there. We do not use GitHub issues for
 support requests, only for bug reports and feature requests.
 .. |room| replace:: ``#synapse:matrix.org``
 .. _room: https://matrix.to/#/#synapse:matrix.org
 Synapse Installation
@@ -112,11 +96,12 @@ Unless you are running a test instance of Synapse on your local machine, in
 general, you will need to enable TLS support before you can successfully
 connect from a client: see `<INSTALL.md#tls-certificates>`_.
-An easy way to get started is to login or register via Element at
+An easy way to get started is to login or register via Riot at
-https://app.element.io/#/login or https://app.element.io/#/register respectively.
+https://riot.im/app/#/login or https://riot.im/app/#/register respectively.
 You will need to change the server you are logging into from ``matrix.org``
 and instead specify a Homeserver URL of ``https://<server_name>:8448``
 (or just ``https://<server_name>`` if you are using a reverse proxy).
 (Leave the identity server as the default - see `Identity servers`_.)
 If you prefer to use another client, refer to our
 `client breakdown <https://matrix.org/docs/projects/clients-matrix>`_.
@@ -133,7 +118,7 @@ it, specify ``enable_registration: true`` in ``homeserver.yaml``. (It is then
 recommended to also set up CAPTCHA - see `<docs/CAPTCHA_SETUP.md>`_.)
 Once ``enable_registration`` is set to ``true``, it is possible to register a
-user via a Matrix client.
+user via `riot.im <https://riot.im/app/#/register>`_ or other Matrix clients.
 Your new user name will be formed partly from the ``server_name``, and partly
 from a localpart you specify when you create the account. Your name will take
@@ -179,6 +164,30 @@ versions of synapse.
 .. _UPGRADE.rst: UPGRADE.rst
 Using PostgreSQL
 ================
 Synapse offers two database engines:
 * `SQLite <https://sqlite.org/>`_
 * `PostgreSQL <https://www.postgresql.org>`_
 By default Synapse uses SQLite in and doing so trades performance for convenience.
 SQLite is only recommended in Synapse for testing purposes or for servers with
 light workloads.
 Almost all installations should opt to use PostreSQL. Advantages include:
 * significant performance improvements due to the superior threading and
  caching model, smarter query optimiser
 * allowing the DB to be run on separate hardware
 * allowing basic active/backup high-availability with a "hot spare" synapse
  pointing at the same DB master, as well as enabling DB replication in
  synapse itself.
 For information on how to install and use PostgreSQL, please see
 `docs/postgres.md <docs/postgres.md>`_.
 .. _reverse-proxy:
 Using a reverse proxy with Synapse
@@ -187,7 +196,7 @@ Using a reverse proxy with Synapse
 It is recommended to put a reverse proxy such as
 `nginx <https://nginx.org/en/docs/http/ngx_http_proxy_module.html>`_,
 `Apache <https://httpd.apache.org/docs/current/mod/mod_proxy_http.html>`_,
-`Caddy <https://caddyserver.com/docs/quick-starts/reverse-proxy>`_ or
+`Caddy <https://caddyserver.com/docs/proxy>`_ or
 `HAProxy <https://www.haproxy.org/>`_ in front of Synapse. One advantage of
 doing so is that it means that you can expose the default https port (443) to
 Matrix clients without needing to run Synapse with root privileges.
@@ -227,9 +236,10 @@ email address.
 Password reset
 ==============
-Users can reset their password through their client. Alternatively, a server admin
+If a user has registered an email address to their account using an identity
-can reset a users password using the `admin API <docs/admin_api/user_admin_api.rst#reset-password>`_
+server, they can request a password-reset token via clients such as Riot.
-or by directly editing the database as shown below.
+
 A manual password reset can be done via direct database access as follows.
 First calculate the hash of the new password::
@@ -238,7 +248,7 @@ First calculate the hash of the new password::
    Confirm password:
    $2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-Then update the ``users`` table in the database::
+Then update the `users` table in the database::
    UPDATE users SET password_hash='$2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
        WHERE name='@test:test.com';
@@ -262,7 +272,7 @@ to install using pip and a virtualenv::
    virtualenv -p python3 env
    source env/bin/activate
-    python -m pip install --no-use-pep517 -e ".[all]"
+    python -m pip install --no-use-pep517 -e .[all]
 This will run a process of downloading and installing all the needed
 dependencies into a virtual env.
@@ -306,9 +316,6 @@ Building internal API documentation::
 Troubleshooting
 ===============
 Need help? Join our community support room on Matrix:
 `#synapse:matrix.org <https://matrix.to/#/#synapse:matrix.org>`_
 Running out of File Handles
 ---------------------------
@@ -386,4 +393,4 @@ something like the following in their logs::
    2019-09-11 19:32:04,271 - synapse.federation.transport.server - 288 - WARNING - GET-11752 - authenticate_request failed: 401: Invalid signature for server <server> with key ed25519:a_EqML: Unable to verify signature for <server>
 This is normally caused by a misconfiguration in your reverse-proxy. See
-`<docs/reverse_proxy.md>`_ and double-check that your settings are correct.
+`<docs/reverse_proxy.rst>`_ and double-check that your settings are correct.
@@ -75,198 +75,6 @@ for example:
     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.18.0
 ====================
 Docker `-py3` suffix will be removed in future versions
 -------------------------------------------------------
 From 10th August 2020, we will no longer publish Docker images with the `-py3` tag suffix. The images tagged with the `-py3` suffix have been identical to the non-suffixed tags since release 0.99.0, and the suffix is obsolete.
 On 10th August, we will remove the `latest-py3` tag. Existing per-release tags (such as `v1.18.0-py3`) will not be removed, but no new `-py3` tags will be added.
 Scripts relying on the `-py3` suffix will need to be updated.
 Redis replication is now recommended in lieu of TCP replication
 ---------------------------------------------------------------
 When setting up worker processes, we now recommend the use of a Redis server for replication. **The old direct TCP connection method is deprecated and will be removed in a future release.**
 See `docs/workers.md <docs/workers.md>`_ for more details.
 Upgrading to v1.14.0
 ====================
 This version includes a database update which is run as part of the upgrade,
 and which may take a couple of minutes in the case of a large server. Synapse
 will not respond to HTTP requests while this update is taking place.
 Upgrading to v1.13.0
 ====================
 Incorrect database migration in old synapse versions
 ----------------------------------------------------
 A bug was introduced in Synapse 1.4.0 which could cause the room directory to
 be incomplete or empty if Synapse was upgraded directly from v1.2.1 or
 earlier, to versions between v1.4.0 and v1.12.x.
 This will *not* be a problem for Synapse installations which were:
 * created at v1.4.0 or later,
 * upgraded via v1.3.x, or
 * upgraded straight from v1.2.1 or earlier to v1.13.0 or later.
 If completeness of the room directory is a concern, installations which are
 affected can be repaired as follows:
 1. Run the following sql from a `psql` or `sqlite3` console:
   .. code:: sql
     INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES
        ('populate_stats_process_rooms', '{}', 'current_state_events_membership');
     INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES
        ('populate_stats_process_users', '{}', 'populate_stats_process_rooms');
 2. Restart synapse.
 New Single Sign-on HTML Templates
 ---------------------------------
 New templates (``sso_auth_confirm.html``, ``sso_auth_success.html``, and
 ``sso_account_deactivated.html``) were added to Synapse. If your Synapse is
 configured to use SSO and a custom  ``sso_redirect_confirm_template_dir``
 configuration then these templates will need to be copied from
 `synapse/res/templates <synapse/res/templates>`_ into that directory.
 Synapse SSO Plugins Method Deprecation
 --------------------------------------
 Plugins using the ``complete_sso_login`` method of
 ``synapse.module_api.ModuleApi`` should update to using the async/await
 version ``complete_sso_login_async`` which includes additional checks. The
 non-async version is considered deprecated.
 Rolling back to v1.12.4 after a failed upgrade
 ----------------------------------------------
 v1.13.0 includes a lot of large changes. If something problematic occurs, you
 may want to roll-back to a previous version of Synapse. Because v1.13.0 also
 includes a new database schema version, reverting that version is also required
 alongside the generic rollback instructions mentioned above. In short, to roll
 back to v1.12.4 you need to:
 1. Stop the server
 2. Decrease the schema version in the database:
   .. code:: sql
      UPDATE schema_version SET version = 57;
 3. Downgrade Synapse by following the instructions for your installation method
   in the "Rolling back to older versions" section above.
 Upgrading to v1.12.0
 ====================
 This version includes a database update which is run as part of the upgrade,
 and which may take some time (several hours in the case of a large
 server). Synapse will not respond to HTTP requests while this update is taking
 place.
 This is only likely to be a problem in the case of a server which is
 participating in many rooms.
 0. As with all upgrades, it is recommended that you have a recent backup of
   your database which can be used for recovery in the event of any problems.
 1. As an initial check to see if you will be affected, you can try running the
   following query from the `psql` or `sqlite3` console. It is safe to run it
   while Synapse is still running.
   .. code:: sql
      SELECT MAX(q.v) FROM (
        SELECT (
          SELECT ej.json AS v
          FROM state_events se INNER JOIN event_json ej USING (event_id)
          WHERE se.room_id=rooms.room_id AND se.type='m.room.create' AND se.state_key=''
          LIMIT 1
        ) FROM rooms WHERE rooms.room_version IS NULL
      ) q;
   This query will take about the same amount of time as the upgrade process: ie,
   if it takes 5 minutes, then it is likely that Synapse will be unresponsive for
   5 minutes during the upgrade.
   If you consider an outage of this duration to be acceptable, no further
   action is necessary and you can simply start Synapse 1.12.0.
   If you would prefer to reduce the downtime, continue with the steps below.
 2. The easiest workaround for this issue is to manually
   create a new index before upgrading. On PostgreSQL, his can be done as follows:
   .. code:: sql
      CREATE INDEX CONCURRENTLY tmp_upgrade_1_12_0_index
      ON state_events(room_id) WHERE type = 'm.room.create';
   The above query may take some time, but is also safe to run while Synapse is
   running.
   We assume that no SQLite users have databases large enough to be
   affected. If you *are* affected, you can run a similar query, omitting the
   ``CONCURRENTLY`` keyword. Note however that this operation may in itself cause
   Synapse to stop running for some time. Synapse admins are reminded that
   `SQLite is not recommended for use outside a test
   environment <https://github.com/matrix-org/synapse/blob/master/README.rst#using-postgresql>`_.
 3. Once the index has been created, the ``SELECT`` query in step 1 above should
   complete quickly. It is therefore safe to upgrade to Synapse 1.12.0.
 4. Once Synapse 1.12.0 has successfully started and is responding to HTTP
   requests, the temporary index can be removed:
   .. code:: sql
      DROP INDEX tmp_upgrade_1_12_0_index;
 Upgrading to v1.10.0
 ====================
 Synapse will now log a warning on start up if used with a PostgreSQL database
 that has a non-recommended locale set.
 See `docs/postgres.md <docs/postgres.md>`_ for details.
 Upgrading to v1.8.0
 ===================
 Specifying a ``log_file`` config option will now cause Synapse to refuse to
 start, and should be replaced by with the ``log_config`` option. Support for
 the ``log_file`` option was removed in v1.3.0 and has since had no effect.
 Upgrading to v1.7.0
 ===================
 In an attempt to configure Synapse in a privacy preserving way, the default
 behaviours of ``allow_public_rooms_without_auth`` and
 ``allow_public_rooms_over_federation`` have been inverted. This means that by
 default, only authenticated users querying the Client/Server API will be able
 to query the room directory, and relatedly that the server will not share
 room directory information with other servers over federation.
 If your installation does not explicitly set these settings one way or the other
 and you want either setting to be ``true`` then it will necessary to update
 your homeserver configuration file accordingly.
 For more details on the surrounding context see our `explainer
 <https://matrix.org/blog/2019/11/09/avoiding-unwelcome-visitors-on-private-matrix-servers>`_.
 Upgrading to v1.5.0
 ===================
@@ -0,0 +1 @@
 Add federation support for cross-signing.
@@ -0,0 +1 @@
 Add a CI job to test the `synapse_port_db` script.
@@ -0,0 +1 @@
 Contributor documentation now mentions script to run linters.
@@ -0,0 +1 @@
 Fix LruCache callback deduplication for Python 3.8. Contributed by @V02460.
@@ -0,0 +1 @@
 Convert EventContext to an attrs.
@@ -0,0 +1 @@
 Increase default room version from 4 to 5, thereby enforcing server key validity period checks.
@@ -0,0 +1 @@
 Remove a room from a server's public rooms list on room upgrade.
@@ -0,0 +1 @@
 Remove a room from a server's public rooms list on room upgrade.
@@ -0,0 +1 @@
 Add support for outbound http proxying via http_proxy/HTTPS_PROXY env vars.
@@ -0,0 +1 @@
 Move `persist_events` out from main data store.
@@ -0,0 +1 @@
 Reduce verbosity of user/room stats.
@@ -0,0 +1 @@
 Reduce impact of debug logging.
@@ -0,0 +1 @@
 Delete keys from key backup when deleting backup versions.
@@ -0,0 +1 @@
 Make notification of cross-signing signatures work with workers.
@@ -0,0 +1 @@
 Modify CAPTCHA_SETUP.md to update the terms `private key` and `public key` to `secret key` and `site key` respectively. Contributed by Yash Jipkate.
@@ -0,0 +1 @@
 Expose some homeserver functionality to spam checkers.
@@ -0,0 +1 @@
 Change cache descriptors to always return deferreds.
@@ -0,0 +1 @@
 Fix incorrect comment regarding the functionality of an `if` statement.
@@ -0,0 +1 @@
 Update CI to run `isort` over the `scripts` and `scripts-dev` directories.
@@ -0,0 +1 @@
 Replace every instance of `logger.warn` method with `logger.warning` as the former is deprecated.
@@ -0,0 +1 @@
 Update `INSTALL.md` Email section to talk about `account_threepid_delegates`.
@@ -0,0 +1 @@
 Fix a small typo in `account_threepid_delegates` configuration option.
@@ -0,0 +1 @@
 Port replication http server endpoints to async/await.
@@ -0,0 +1 @@
 Port room rest handlers to async/await.
@@ -0,0 +1 @@
 Add a CI job to test the `synapse_port_db` script.
@@ -0,0 +1 @@
 Remove redundant CLI parameters on CI's `flake8` step.
@@ -0,0 +1 @@
 Fix exception when remote servers attempt to join a room that they're not allowed to join.
@@ -0,0 +1 @@
 Port `federation_server.py` to async/await.
@@ -0,0 +1 @@
 Port receipt and read markers to async/wait.
@@ -0,0 +1 @@
 Prevent errors from appearing on Synapse startup if `git` is not installed.
@@ -0,0 +1 @@
 Change cache descriptors to always return deferreds.
@@ -0,0 +1 @@
 Split out state storage into separate data store.
@@ -0,0 +1 @@
 Split out state storage into separate data store.
@@ -0,0 +1 @@
 Refactor EventContext for clarity.
@@ -0,0 +1 @@
 Move `persist_events` out from main data store.
@@ -0,0 +1 @@
 Implement label-based filtering on `/sync` and `/messages` ([MSC2326](https://github.com/matrix-org/matrix-doc/pull/2326)).
@@ -0,0 +1 @@
 Update the version of black used to 19.10b0.
@@ -0,0 +1 @@
 Add some documentation about worker replication.
@@ -0,0 +1 @@
 Appservice requests will no longer contain a double slash prefix when the appservice url provided ends in a slash.
@@ -0,0 +1 @@
 Fix `/purge_room` admin API.
@@ -0,0 +1 @@
 Implement label-based filtering on `/sync` and `/messages` ([MSC2326](https://github.com/matrix-org/matrix-doc/pull/2326)).
@@ -0,0 +1 @@
 Document the use of `lint.sh` for code style enforcement & extend it to run on specified paths only.
@@ -0,0 +1 @@
 Fix the `hidden` field in the `devices` table for SQLite versions prior to 3.23.0.
@@ -0,0 +1 @@
 Replace every instance of `logger.warn` method with `logger.warning` as the former is deprecated.
@@ -0,0 +1 @@
 Add optional python dependencies and dependant binary libraries to snapcraft packaging.
@@ -0,0 +1 @@
 Remove the dependency on psutil and replace functionality with the stdlib `resource` module.
@@ -0,0 +1 @@
 Improve documentation for EventContext fields.
@@ -0,0 +1 @@
 Fix bug which casued rejected events to be persisted with the wrong room state.
@@ -0,0 +1 @@
 Add some checks that we aren't using state from rejected events.
@@ -0,0 +1 @@
 Remove the dependency on psutil and replace functionality with the stdlib `resource` module.
@@ -0,0 +1 @@
 Prevent the server taking a long time to start up when guest registration is enabled.
@@ -0,0 +1 @@
 Implement label-based filtering on `/sync` and `/messages` ([MSC2326](https://github.com/matrix-org/matrix-doc/pull/2326)).
@@ -0,0 +1 @@
 Add continuous integration for python 3.8.
@@ -0,0 +1 @@
 Correct spacing/case of various instances of the word "homeserver".
@@ -0,0 +1 @@
 Fix bug where upgrading a guest account to a full user would fail when account validity is enabled.
@@ -0,0 +1 @@
 Temporarily blacklist the failing unit test PurgeRoomTestCase.test_purge_room.
@@ -0,0 +1 @@
 Fix `to_device` stream ID getting reset every time Synapse restarts, which had the potential to cause unable to decrypt errors.
@@ -0,0 +1 @@
 Fix `to_device` stream ID getting reset every time Synapse restarts, which had the potential to cause unable to decrypt errors.
@@ -17,6 +17,9 @@
 """ Starts a synapse client console. """
 from __future__ import print_function
 from twisted.internet import reactor, defer, threads
 from http import TwistedHttpClient
 import argparse
 import cmd
 import getpass
@@ -25,14 +28,12 @@ import shlex
 import sys
 import time
 import urllib
 from http import TwistedHttpClient
 import nacl.encoding
 import nacl.signing
 import urlparse
 from signedjson.sign import SignatureVerifyException, verify_signed_json
-from twisted.internet import defer, reactor, threads
+import nacl.signing
 import nacl.encoding
 from signedjson.sign import verify_signed_json, SignatureVerifyException
 CONFIG_JSON = "cmdclient_config.json"
@@ -492,7 +493,7 @@ class SynapseCmd(cmd.Cmd):
        "list messages <roomid> from=END&to=START&limit=3"
        """
        args = self._parse(line, ["type", "roomid", "qp"])
-        if "type" not in args or "roomid" not in args:
+        if not "type" in args or not "roomid" in args:
            print("Must specify type and room ID.")
            return
        if args["type"] not in ["members", "messages"]:
@@ -507,7 +508,7 @@ class SynapseCmd(cmd.Cmd):
                try:
                    key_value = key_value_str.split("=")
                    qp[key_value[0]] = key_value[1]
-                except Exception:
+                except:
                    print("Bad query param: %s" % key_value)
                    return
@@ -584,7 +585,7 @@ class SynapseCmd(cmd.Cmd):
                parsed_url = urlparse.urlparse(args["path"])
                qp.update(urlparse.parse_qs(parsed_url.query))
                args["path"] = parsed_url.path
-            except Exception:
+            except:
                pass
        reactor.callFromThread(
@@ -609,15 +610,13 @@ class SynapseCmd(cmd.Cmd):
    @defer.inlineCallbacks
    def _do_event_stream(self, timeout):
-        res = yield defer.ensureDeferred(
+        res = yield self.http_client.get_json(
-            self.http_client.get_json(
+            self._url() + "/events",
-                self._url() + "/events",
+            {
-                {
+                "access_token": self._tok(),
-                    "access_token": self._tok(),
+                "timeout": str(timeout),
-                    "timeout": str(timeout),
+                "from": self.event_stream_token,
-                    "from": self.event_stream_token,
+            },
                },
            )
        )
        print(json.dumps(res, indent=4))
@@ -773,10 +772,10 @@ def main(server_url, identity_server_url, username, token, config_path):
            syn_cmd.config = json.load(config)
            try:
                http_client.verbose = "on" == syn_cmd.config["verbose"]
-            except Exception:
+            except:
                pass
            print("Loaded config from %s" % config_path)
-    except Exception:
+    except:
        pass
    # Twisted-specific: Runs the command processor in Twisted's event loop
@@ -14,14 +14,14 @@
 # limitations under the License.
 from __future__ import print_function
 from twisted.web.client import Agent, readBody
 from twisted.web.http_headers import Headers
 from twisted.internet import defer, reactor
 from pprint import pformat
 import json
 import urllib
 from pprint import pformat
 from twisted.internet import defer, reactor
 from twisted.web.client import Agent, readBody
 from twisted.web.http_headers import Headers
 class HttpClient(object):
@@ -15,9 +15,10 @@ services:
    restart: unless-stopped
    # See the readme for a full documentation of the environment settings
    environment:
-      - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
+      - SYNAPSE_CONFIG_PATH=/etc/homeserver.yaml
    volumes:
      # You may either store all the files in a local folder
      - ./matrix-config:/etc
      - ./files:/data
      # .. or you may split this between different storage points
      # - ./files:/data
@@ -50,14 +51,11 @@ services:
      - traefik.http.routers.https-synapse.tls.certResolver=le-ssl
  db:
-    image: docker.io/postgres:12-alpine
+    image: docker.io/postgres:10-alpine
    # Change that password, of course!
    environment:
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=changeme
      # ensure the database gets created correctly
      # https://github.com/matrix-org/synapse/blob/master/docs/postgres.md#set-up-database
      - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      # You may store the database tables in a local folder..
      - ./schemas:/var/lib/postgresql/data
@@ -28,24 +28,27 @@ Currently assumes the local address is localhost:<port>
 """
 from synapse.federation import ReplicationHandler
 from synapse.federation.units import Pdu
 from synapse.util import origin_from_ucid
 from synapse.app.homeserver import SynapseHomeServer
 # from synapse.logging.utils import log_function
 from twisted.internet import reactor, defer
 from twisted.python import log
 import argparse
 import curses.wrapper
 import json
 import logging
 import os
 import re
 import cursesio
-
+import curses.wrapper
 from twisted.internet import defer, reactor
 from twisted.python import log
 from synapse.app.homeserver import SynapseHomeServer
 from synapse.federation import ReplicationHandler
 from synapse.federation.units import Pdu
 from synapse.util import origin_from_ucid
 # from synapse.logging.utils import log_function
 logger = logging.getLogger("example")
@@ -72,7 +75,7 @@ class InputOutput(object):
        """
        try:
-            m = re.match(r"^join (\S+)$", line)
+            m = re.match("^join (\S+)$", line)
            if m:
                # The `sender` wants to join a room.
                (room_name,) = m.groups()
@@ -81,7 +84,7 @@ class InputOutput(object):
                # self.print_line("OK.")
                return
-            m = re.match(r"^invite (\S+) (\S+)$", line)
+            m = re.match("^invite (\S+) (\S+)$", line)
            if m:
                # `sender` wants to invite someone to a room
                room_name, invitee = m.groups()
@@ -90,7 +93,7 @@ class InputOutput(object):
                # self.print_line("OK.")
                return
-            m = re.match(r"^send (\S+) (.*)$", line)
+            m = re.match("^send (\S+) (.*)$", line)
            if m:
                # `sender` wants to message a room
                room_name, body = m.groups()
@@ -99,7 +102,7 @@ class InputOutput(object):
                # self.print_line("OK.")
                return
-            m = re.match(r"^backfill (\S+)$", line)
+            m = re.match("^backfill (\S+)$", line)
            if m:
                # we want to backfill a room
                (room_name,) = m.groups()
@@ -198,6 +201,16 @@ class HomeServer(ReplicationHandler):
                % (pdu.context, pdu.pdu_type, json.dumps(pdu.content))
            )
    # def on_state_change(self, pdu):
    ##self.output.print_line("#%s (state) %s *** %s" %
    ##(pdu.context, pdu.state_key, pdu.pdu_type)
    ##)
    # if "joinee" in pdu.content:
    # self._on_join(pdu.context, pdu.content["joinee"])
    # elif "invitee" in pdu.content:
    # self._on_invite(pdu.origin, pdu.context, pdu.content["invitee"])
    def _on_message(self, pdu):
        """ We received a message
        """
@@ -301,7 +314,7 @@ class HomeServer(ReplicationHandler):
        return self.replication_layer.backfill(dest, room_name, limit)
    def _get_room_remote_servers(self, room_name):
-        return list(self.joined_rooms.setdefault(room_name).servers)
+        return [i for i in self.joined_rooms.setdefault(room_name).servers]
    def _get_or_create_room(self, room_name):
        return self.joined_rooms.setdefault(room_name, Room(room_name))
@@ -321,7 +334,7 @@ def main(stdscr):
    user = args.user
    server_name = origin_from_ucid(user)
-    # Set up logging
+    ## Set up logging ##
    root_logger = logging.getLogger()
@@ -341,7 +354,7 @@ def main(stdscr):
    observer = log.PythonLoggingObserver()
    observer.start()
-    # Set up synapse server
+    ## Set up synapse server
    curses_stdio = cursesio.CursesStdIO(stdscr)
    input_output = InputOutput(curses_stdio, user)
@@ -355,16 +368,16 @@ def main(stdscr):
    input_output.set_home_server(hs)
-    # Add input_output logger
+    ## Add input_output logger
    io_logger = IOLoggerHandler(input_output)
    io_logger.setFormatter(formatter)
    root_logger.addHandler(io_logger)
-    # Start!
+    ## Start! ##
    try:
        port = int(server_name.split(":")[1])
-    except Exception:
+    except:
        port = 12345
    app_hs.get_http_server().start_listening(port)
@@ -1,6 +1,6 @@
 # Using the Synapse Grafana dashboard
 0. Set up Prometheus and Grafana. Out of scope for this readme. Useful documentation about using Grafana with Prometheus: http://docs.grafana.org/features/datasources/prometheus/
-1. Have your Prometheus scrape your Synapse. https://github.com/matrix-org/synapse/blob/master/docs/metrics-howto.md
+1. Have your Prometheus scrape your Synapse. https://github.com/matrix-org/synapse/blob/master/docs/metrics-howto.rst
 2. Import dashboard into Grafana. Download `synapse.json`. Import it to Grafana and select the correct Prometheus datasource. http://docs.grafana.org/reference/export_import/
 3. Set up additional recording rules
@@ -1,13 +1,5 @@
 from __future__ import print_function
 import argparse
 import cgi
 import datetime
 import json
 import pydot
 import urllib2
 # Copyright 2014-2016 OpenMarket Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -23,6 +15,15 @@ import urllib2
 # limitations under the License.
 import sqlite3
 import pydot
 import cgi
 import json
 import datetime
 import argparse
 import urllib2
 def make_name(pdu_id, origin):
    return "%s@%s" % (pdu_id, origin)
@@ -32,7 +33,7 @@ def make_graph(pdus, room, filename_prefix):
    node_map = {}
    origins = set()
-    colors = {"red", "green", "blue", "yellow", "purple"}
+    colors = set(("red", "green", "blue", "yellow", "purple"))
    for pdu in pdus:
        origins.add(pdu.get("origin"))
@@ -48,7 +49,7 @@ def make_graph(pdus, room, filename_prefix):
        try:
            c = colors.pop()
            color_map[o] = c
-        except Exception:
+        except:
            print("Run out of colours!")
            color_map[o] = "black"
@@ -13,13 +13,12 @@
 # limitations under the License.
 import argparse
 import cgi
 import datetime
 import json
 import sqlite3
 import pydot
 import cgi
 import json
 import datetime
 import argparse
 from synapse.events import FrozenEvent
 from synapse.util.frozenutils import unfreeze
@@ -99,7 +98,7 @@ def make_graph(db_name, room_id, file_prefix, limit):
        for prev_id, _ in event.prev_events:
            try:
                end_node = node_map[prev_id]
-            except Exception:
+            except:
                end_node = pydot.Node(name=prev_id, label="<<b>%s</b>>" % (prev_id,))
                node_map[prev_id] = end_node
@@ -1,15 +1,5 @@
 from __future__ import print_function
 import argparse
 import cgi
 import datetime
 import pydot
 import simplejson as json
 from synapse.events import FrozenEvent
 from synapse.util.frozenutils import unfreeze
 # Copyright 2016 OpenMarket Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -25,6 +15,18 @@ from synapse.util.frozenutils import unfreeze
 # limitations under the License.
 import pydot
 import cgi
 import simplejson as json
 import datetime
 import argparse
 from synapse.events import FrozenEvent
 from synapse.util.frozenutils import unfreeze
 from six import string_types
 def make_graph(file_name, room_id, file_prefix, limit):
    print("Reading lines")
    with open(file_name) as f:
@@ -60,7 +62,7 @@ def make_graph(file_name, room_id, file_prefix, limit):
        for key, value in unfreeze(event.get_dict()["content"]).items():
            if value is None:
                value = "<null>"
-            elif isinstance(value, str):
+            elif isinstance(value, string_types):
                pass
            else:
                value = json.dumps(value)
@@ -106,7 +108,7 @@ def make_graph(file_name, room_id, file_prefix, limit):
        for prev_id, _ in event.prev_events:
            try:
                end_node = node_map[prev_id]
-            except Exception:
+            except:
                end_node = pydot.Node(name=prev_id, label="<<b>%s</b>>" % (prev_id,))
                node_map[prev_id] = end_node
@@ -12,15 +12,15 @@ npm install jquery jsdom
 """
 from __future__ import print_function
 import json
 import subprocess
 import time
 import gevent
 import grequests
 from BeautifulSoup import BeautifulSoup
 import json
 import urllib
 import subprocess
 import time
-ACCESS_TOKEN = ""
+# ACCESS_TOKEN="" #
 MATRIXBASE = "https://matrix.org/_matrix/client/api/v1/"
 MYUSERNAME = "@davetest:matrix.org"
@@ -1,12 +1,10 @@
 #!/usr/bin/env python
 from __future__ import print_function
-
+from argparse import ArgumentParser
 import json
 import requests
 import sys
 import urllib
 from argparse import ArgumentParser
 import requests
 try:
    raw_input
@@ -1,2 +1,150 @@
-The documentation for using systemd to manage synapse workers is now part of
+# Setup Synapse with Workers and Systemd
-the main synapse distribution. See [docs/systemd-with-workers](../../docs/systemd-with-workers).
+
 This is a setup for managing synapse with systemd including support for
 managing workers. It provides a `matrix-synapse`, as well as a
 `matrix-synapse-worker@` service for any workers you require. Additionally to
 group the required services it sets up a `matrix.target`. You can use this to
 automatically start any bot- or bridge-services. More on this in
 [Bots and Bridges](#bots-and-bridges).
 See the folder [system](system) for any service and target files.
 The folder [workers](workers) contains an example configuration for the
 `federation_reader` worker. Pay special attention to the name of the
 configuration file. In order to work with the `matrix-synapse-worker@.service`
 service, it needs to have the exact same name as the worker app.
 This setup expects neither the homeserver nor any workers to fork. Forking is
 handled by systemd.
 ## Setup
 1. Adjust your matrix configs. Make sure that the worker config files have the
 exact same name as the worker app. Compare `matrix-synapse-worker@.service` for
 why. You can find an example worker config in the [workers](workers) folder. See
 below for relevant settings in the `homeserver.yaml`.
 2. Copy the `*.service` and `*.target` files in [system](system) to
 `/etc/systemd/system`.
 3. `systemctl enable matrix-synapse.service` this adds the homeserver
 app to the `matrix.target`
 4. *Optional.* `systemctl enable
 matrix-synapse-worker@federation_reader.service` this adds the federation_reader
 app to the `matrix-synapse.service`
 5. *Optional.* Repeat step 4 for any additional workers you require.
 6. *Optional.* Add any bots or bridges by enabling them.
 7. Start all matrix related services via `systemctl start matrix.target`
 8. *Optional.* Enable autostart of all matrix related services on system boot
 via `systemctl enable matrix.target`
 ## Usage
 After you have setup you can use the following commands to manage your synapse
 installation:
 ```
 # Start matrix-synapse, all workers and any enabled bots or bridges.
 systemctl start matrix.target
 # Restart matrix-synapse and all workers (not necessarily restarting bots
 # or bridges, see "Bots and Bridges")
 systemctl restart matrix-synapse.service
 # Stop matrix-synapse and all workers (not necessarily restarting bots
 # or bridges, see "Bots and Bridges")
 systemctl stop matrix-synapse.service
 # Restart a specific worker (i. e. federation_reader), the homeserver is
 # unaffected by this.
 systemctl restart matrix-synapse-worker@federation_reader.service
 # Add a new worker (assuming all configs are setup already)
 systemctl enable matrix-synapse-worker@federation_writer.service
 systemctl restart matrix-synapse.service
 ```
 ## The Configs
 Make sure the `worker_app` is set in the `homeserver.yaml` and it does not fork.
 ```
 worker_app: synapse.app.homeserver 
 daemonize: false
 ```
 None of the workers should fork, as forking is handled by systemd. Hence make
 sure this is present in all worker config files.
 ```
 worker_daemonize: false
 ```
 The config files of all workers are expected to be located in
 `/etc/matrix-synapse/workers`. If you want to use a different location you have
 to edit the provided `*.service` files accordingly.  
 ## Bots and Bridges
 Most bots and bridges do not care if the homeserver goes down or is restarted.
 Depending on the implementation this may crash them though. So look up the docs
 or ask the community of the specific bridge or bot you want to run to make sure
 you choose the correct setup.
 Whichever configuration you choose, after the setup the following will enable
 automatically starting (and potentially restarting) your bot/bridge with the
 `matrix.target`.
 ```
 systemctl enable <yourBotOrBridgeName>.service
 ```
 **Note** that from an inactive synapse the bots/bridges will only be started with
 synapse if you start the `matrix.target`, not if you start the
 `matrix-synapse.service`. This is on purpose. Think of `matrix-synapse.service`
 as *just* synapse, but `matrix.target` being anything matrix related, including
 synapse and any and all enabled bots and bridges.
 ### Start with synapse but ignore synapse going down
 If the bridge can handle shutdowns of the homeserver you'll want to install the
 service in the `matrix.target` and optionally add a
 `After=matrix-synapse.service` dependency to have the bot/bridge start after
 synapse on starting everything.
 In this case the service file should look like this.
 ```
 [Unit]
 # ...
 # Optional, this will only ensure that if you start everything, synapse will
 # be started before the bot/bridge will be started.
 After=matrix-synapse.service
 [Service]
 # ...
 [Install]
 WantedBy=matrix.target
 ```
 ### Stop/restart when synapse stops/restarts
 If the bridge can't handle shutdowns of the homeserver you'll still want to
 install the service in the `matrix.target` but also have to specify the
 `After=matrix-synapse.service` *and* `BindsTo=matrix-synapse.service`
 dependencies to have the bot/bridge stop/restart with synapse.
 In this case the service file should look like this.
 ```
 [Unit]
 # ...
 # Mandatory
 After=matrix-synapse.service
 BindsTo=matrix-synapse.service
 [Service]
 # ...
 [Install]
 WantedBy=matrix.target
 ```
@@ -0,0 +1,19 @@
 [Unit]
 Description=Synapse Matrix Worker
 After=matrix-synapse.service
 BindsTo=matrix-synapse.service
 [Service]
 Type=notify
 NotifyAccess=main
 User=matrix-synapse
 WorkingDirectory=/var/lib/matrix-synapse
 EnvironmentFile=/etc/default/matrix-synapse
 ExecStart=/opt/venvs/matrix-synapse/bin/python -m synapse.app.%i --config-path=/etc/matrix-synapse/homeserver.yaml --config-path=/etc/matrix-synapse/conf.d/ --config-path=/etc/matrix-synapse/workers/%i.yaml
 ExecReload=/bin/kill -HUP $MAINPID
 Restart=always
 RestartSec=3
 SyslogIdentifier=matrix-synapse-%i
 [Install]
 WantedBy=matrix-synapse.service
@@ -1,8 +1,5 @@
 [Unit]
-Description=Synapse master
+Description=Synapse Matrix Homeserver
 # This service should be restarted when the synapse target is restarted.
 PartOf=matrix-synapse.target
 [Service]
 Type=notify
@@ -18,4 +15,4 @@ RestartSec=3
 SyslogIdentifier=matrix-synapse
 [Install]
-WantedBy=matrix-synapse.target
+WantedBy=matrix.target
@@ -0,0 +1,7 @@
 [Unit]
 Description=Contains matrix services like synapse, bridges and bots
 After=network.target
 AllowIsolate=no
 [Install]
 WantedBy=multi-user.target
@@ -1,7 +1,7 @@
 worker_app: synapse.app.federation_reader
 worker_name: federation_reader1
 worker_replication_host: 127.0.0.1
 worker_replication_port: 9092
 worker_replication_http_port: 9093
 worker_listeners:
@@ -10,4 +10,5 @@ worker_listeners:
      resources:
          - names: [federation]
 worker_daemonize: false
 worker_log_config: /etc/matrix-synapse/federation-reader-log.yaml
@@ -1,17 +0,0 @@
 # Setup Synapse with Systemd
 This is a setup for managing synapse with a user contributed systemd unit 
 file. It provides a `matrix-synapse` systemd unit file that should be tailored 
 to accommodate your installation in accordance with the installation 
 instructions provided in [installation instructions](../../INSTALL.md).
 ## Setup
 1. Under the service section, ensure the `User` variable matches which user
 you installed synapse under and wish to run it as. 
 2. Under the service section, ensure the `WorkingDirectory` variable matches
 where you have installed synapse.
 3. Under the service section, ensure the `ExecStart` variable matches the
 appropriate locations of your installation.
 4. Copy the `matrix-synapse.service` to `/etc/systemd/system/`
 5. Start Synapse: `sudo systemctl start matrix-synapse`
 6. Verify Synapse is running: `sudo systemctl status matrix-synapse`
 7. *optional* Enable Synapse to start at system boot: `sudo systemctl enable matrix-synapse`
@@ -4,20 +4,14 @@
 #    systemctl enable matrix-synapse
 #    systemctl start matrix-synapse
 #
 # This assumes that Synapse has been installed by a user named
 # synapse.
 #
 # This assumes that Synapse has been installed in a virtualenv in
-# the user's home directory: `/home/synapse/synapse/env`.
+# /opt/synapse/env.
 #
 # **NOTE:** This is an example service file that may change in the future. If you
 # wish to use this please copy rather than symlink it.
 [Unit]
 Description=Synapse Matrix homeserver
 # If you are using postgresql to persist data, uncomment this line to make sure
 # synapse starts after the postgresql service.
 # After=postgresql.service
 [Service]
 Type=notify
@@ -28,8 +22,8 @@ Restart=on-abort
 User=synapse
 Group=nogroup
-WorkingDirectory=/home/synapse/synapse
+WorkingDirectory=/opt/synapse
-ExecStart=/home/synapse/synapse/env/bin/python -m synapse.app.homeserver --config-path=/home/synapse/synapse/homeserver.yaml
+ExecStart=/opt/synapse/env/bin/python -m synapse.app.homeserver --config-path=/opt/synapse/homeserver.yaml
 SyslogIdentifier=matrix-synapse
 # adjust the cache factor if necessary
@@ -36,6 +36,7 @@ esac
 dh_virtualenv \
    --install-suffix "matrix-synapse" \
    --builtin-venv \
    --setuptools \
    --python "$SNAKE" \
    --upgrade-pip \
    --preinstall="lxml" \
@@ -84,9 +85,6 @@ PYTHONPATH="$tmpdir" \
 ' > "${PACKAGE_BUILD_DIR}/etc/matrix-synapse/homeserver.yaml"
 # build the log config file
 "${TARGET_PYTHON}" -B "${VIRTUALENV_DIR}/bin/generate_log_config" \
        --output-file="${PACKAGE_BUILD_DIR}/etc/matrix-synapse/log.yaml"
 # add a dependency on the right version of python to substvars.
 PYPKG=`basename $SNAKE`
@@ -1,206 +1,3 @@
 matrix-synapse-py3 (1.19.2) stable; urgency=medium
  * New synapse release 1.19.2.
 -- Synapse Packaging team <packages@matrix.org>  Wed, 16 Sep 2020 12:50:30 +0100
 matrix-synapse-py3 (1.19.1) stable; urgency=medium
  * New synapse release 1.19.1.
 -- Synapse Packaging team <packages@matrix.org>  Thu, 27 Aug 2020 10:50:19 +0100
 matrix-synapse-py3 (1.19.0) stable; urgency=medium
  [ Synapse Packaging team ]
  * New synapse release 1.19.0.
  [ Aaron Raimist ]
  * Fix outdated documentation for SYNAPSE_CACHE_FACTOR
 -- Synapse Packaging team <packages@matrix.org>  Mon, 17 Aug 2020 14:06:42 +0100
 matrix-synapse-py3 (1.18.0) stable; urgency=medium
  * New synapse release 1.18.0.
 -- Synapse Packaging team <packages@matrix.org>  Thu, 30 Jul 2020 10:55:53 +0100
 matrix-synapse-py3 (1.17.0) stable; urgency=medium
  * New synapse release 1.17.0.
 -- Synapse Packaging team <packages@matrix.org>  Mon, 13 Jul 2020 10:20:31 +0100
 matrix-synapse-py3 (1.16.1) stable; urgency=medium
  * New synapse release 1.16.1.
 -- Synapse Packaging team <packages@matrix.org>  Fri, 10 Jul 2020 12:09:24 +0100
 matrix-synapse-py3 (1.17.0rc1) stable; urgency=medium
  * New synapse release 1.17.0rc1.
 -- Synapse Packaging team <packages@matrix.org>  Thu, 09 Jul 2020 16:53:12 +0100
 matrix-synapse-py3 (1.16.0) stable; urgency=medium
  * New synapse release 1.16.0.
 -- Synapse Packaging team <packages@matrix.org>  Wed, 08 Jul 2020 11:03:48 +0100
 matrix-synapse-py3 (1.15.2) stable; urgency=medium
  * New synapse release 1.15.2.
 -- Synapse Packaging team <packages@matrix.org>  Thu, 02 Jul 2020 10:34:00 -0400
 matrix-synapse-py3 (1.15.1) stable; urgency=medium
  * New synapse release 1.15.1.
 -- Synapse Packaging team <packages@matrix.org>  Tue, 16 Jun 2020 10:27:50 +0100
 matrix-synapse-py3 (1.15.0) stable; urgency=medium
  * New synapse release 1.15.0.
 -- Synapse Packaging team <packages@matrix.org>  Thu, 11 Jun 2020 13:27:06 +0100
 matrix-synapse-py3 (1.14.0) stable; urgency=medium
  * New synapse release 1.14.0.
 -- Synapse Packaging team <packages@matrix.org>  Thu, 28 May 2020 10:37:27 +0000
 matrix-synapse-py3 (1.13.0) stable; urgency=medium
  [ Patrick Cloke ]
  * Add information about .well-known files to Debian installation scripts.
  [ Synapse Packaging team ]
  * New synapse release 1.13.0.
 -- Synapse Packaging team <packages@matrix.org>  Tue, 19 May 2020 09:16:56 -0400
 matrix-synapse-py3 (1.12.4) stable; urgency=medium
  * New synapse release 1.12.4.
 -- Synapse Packaging team <packages@matrix.org>  Thu, 23 Apr 2020 10:58:14 -0400
 matrix-synapse-py3 (1.12.3) stable; urgency=medium
  [ Richard van der Hoff ]
  * Update the Debian build scripts to handle the new installation paths
   for the support libraries introduced by Pillow 7.1.1.
  [ Synapse Packaging team ]
  * New synapse release 1.12.3.
 -- Synapse Packaging team <packages@matrix.org>  Fri, 03 Apr 2020 10:55:03 +0100
 matrix-synapse-py3 (1.12.2) stable; urgency=medium
  * New synapse release 1.12.2.
 -- Synapse Packaging team <packages@matrix.org>  Mon, 02 Apr 2020 19:02:17 +0000
 matrix-synapse-py3 (1.12.1) stable; urgency=medium
  * New synapse release 1.12.1.
 -- Synapse Packaging team <packages@matrix.org>  Mon, 02 Apr 2020 11:30:47 +0000
 matrix-synapse-py3 (1.12.0) stable; urgency=medium
  * New synapse release 1.12.0.
 -- Synapse Packaging team <packages@matrix.org>  Mon, 23 Mar 2020 12:13:03 +0000
 matrix-synapse-py3 (1.11.1) stable; urgency=medium
  * New synapse release 1.11.1.
 -- Synapse Packaging team <packages@matrix.org>  Tue, 03 Mar 2020 15:01:22 +0000
 matrix-synapse-py3 (1.11.0) stable; urgency=medium
  * New synapse release 1.11.0.
 -- Synapse Packaging team <packages@matrix.org>  Fri, 21 Feb 2020 08:54:34 +0000
 matrix-synapse-py3 (1.10.1) stable; urgency=medium
  * New synapse release 1.10.1.
 -- Synapse Packaging team <packages@matrix.org>  Mon, 17 Feb 2020 16:27:28 +0000
 matrix-synapse-py3 (1.10.0) stable; urgency=medium
  * New synapse release 1.10.0.
 -- Synapse Packaging team <packages@matrix.org>  Wed, 12 Feb 2020 12:18:54 +0000
 matrix-synapse-py3 (1.9.1) stable; urgency=medium
  * New synapse release 1.9.1.
 -- Synapse Packaging team <packages@matrix.org>  Tue, 28 Jan 2020 13:09:23 +0000
 matrix-synapse-py3 (1.9.0) stable; urgency=medium
  * New synapse release 1.9.0.
 -- Synapse Packaging team <packages@matrix.org>  Thu, 23 Jan 2020 12:56:31 +0000
 matrix-synapse-py3 (1.8.0) stable; urgency=medium
  [ Richard van der Hoff ]
  * Automate generation of the default log configuration file.
  [ Synapse Packaging team ]
  * New synapse release 1.8.0.
 -- Synapse Packaging team <packages@matrix.org>  Thu, 09 Jan 2020 11:39:27 +0000
 matrix-synapse-py3 (1.7.3) stable; urgency=medium
  * New synapse release 1.7.3.
 -- Synapse Packaging team <packages@matrix.org>  Tue, 31 Dec 2019 10:45:04 +0000
 matrix-synapse-py3 (1.7.2) stable; urgency=medium
  * New synapse release 1.7.2.
 -- Synapse Packaging team <packages@matrix.org>  Fri, 20 Dec 2019 10:56:50 +0000
 matrix-synapse-py3 (1.7.1) stable; urgency=medium
  * New synapse release 1.7.1.
 -- Synapse Packaging team <packages@matrix.org>  Wed, 18 Dec 2019 09:37:59 +0000
 matrix-synapse-py3 (1.7.0) stable; urgency=medium
  * New synapse release 1.7.0.
 -- Synapse Packaging team <packages@matrix.org>  Fri, 13 Dec 2019 10:19:38 +0000
 matrix-synapse-py3 (1.6.1) stable; urgency=medium
  * New synapse release 1.6.1.
 -- Synapse Packaging team <packages@matrix.org>  Thu, 28 Nov 2019 11:10:40 +0000
 matrix-synapse-py3 (1.6.0) stable; urgency=medium
  * New synapse release 1.6.0.
 -- Synapse Packaging team <packages@matrix.org>  Tue, 26 Nov 2019 12:15:40 +0000
 matrix-synapse-py3 (1.5.1) stable; urgency=medium
  * New synapse release 1.5.1.
@@ -1 +1,2 @@
 debian/log.yaml etc/matrix-synapse
 debian/manage_debconf.pl /opt/venvs/matrix-synapse/lib/
@@ -0,0 +1,36 @@
 version: 1
 formatters:
  precise:
   format: '%(asctime)s - %(name)s - %(lineno)d - %(levelname)s - %(request)s- %(message)s'
 filters:
  context:
    (): synapse.logging.context.LoggingContextFilter
    request: ""
 handlers:
  file:
    class: logging.handlers.RotatingFileHandler
    formatter: precise
    filename: /var/log/matrix-synapse/homeserver.log
    maxBytes: 104857600
    backupCount: 10
    filters: [context]
    encoding: utf8
  console:
    class: logging.StreamHandler
    formatter: precise
    level: WARN
 loggers:
    synapse:
        level: INFO
    synapse.storage.SQL:
        level: INFO
 root:
    level: INFO
    handlers: [file, console]
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Andrew Morgan	5f4b59d0ce	Switch to using a delta file	2019-11-19 10:49:40 +00:00
Andrew Morgan	bc7a623980	Add changelog	2019-11-18 17:50:08 +00:00
Andrew Morgan	1d9b29190b	Switch INSERT + UPDATE to UPSERT	2019-11-18 17:47:41 +00:00
		`@@ -0,0 +1 @@`
							Add a CI job to test the `synapse_port_db` script.
		`@@ -0,0 +1 @@`
							`Contributor documentation now mentions script to run linters.`
		`@@ -0,0 +1 @@`
							`Fix LruCache callback deduplication for Python 3.8. Contributed by @V02460.`
		`@@ -0,0 +1 @@`
							`Increase default room version from 4 to 5, thereby enforcing server key validity period checks.`
		`@@ -0,0 +1 @@`
							`Remove a room from a server's public rooms list on room upgrade.`
		`@@ -0,0 +1 @@`
							`Add support for outbound http proxying via http_proxy/HTTPS_PROXY env vars.`
		`@@ -0,0 +1 @@`
							Move `persist_events` out from main data store.
		`@@ -0,0 +1 @@`
							`Delete keys from key backup when deleting backup versions.`
		`@@ -0,0 +1 @@`
							`Make notification of cross-signing signatures work with workers.`