deploy: b2c5e79291b9f93cdb39c9a6f7de50e62f45e64e

1 files changed, 235 insertions, 125 deletions

diff --git a/latest/print.html b/latest/print.html
index dc2b03ddb4..1b32b73ca4 100644
--- a/latest/print.html
+++ b/latest/print.html
@@ -101,7 +101,7 @@
 
         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <div class="sidebar-scrollbox">
-                <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="setup/forward_proxy.html">Configuring a Forward/Outbound Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrade.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="templates.html">Templates</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="development/url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules/index.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/writing_a_module.html">Writing a module</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/spam_checker_callbacks.html">Spam checker callbacks</a></li><li class="chapter-item expanded "><a href="modules/third_party_rules_callbacks.html">Third-party rules callbacks</a></li><li class="chapter-item expanded "><a href="modules/presence_router_callbacks.html">Presence router callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_validity_callbacks.html">Account validity callbacks</a></li><li class="chapter-item expanded "><a href="modules/porting_legacy_module.html">Porting a legacy module to the new interface</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/registration_tokens.html">Registration Tokens</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="development/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="replication.html">Replication</a></li><li class="chapter-item expanded "><a href="tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="development/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><a href="development/room-dag-concepts.html">Room DAG concepts</a></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="deprecation_policy.html">Dependency Deprecation Policy</a></li></ol>
+                <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="setup/forward_proxy.html">Configuring a Forward/Outbound Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrade.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="templates.html">Templates</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="development/url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules/index.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/writing_a_module.html">Writing a module</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/spam_checker_callbacks.html">Spam checker callbacks</a></li><li class="chapter-item expanded "><a href="modules/third_party_rules_callbacks.html">Third-party rules callbacks</a></li><li class="chapter-item expanded "><a href="modules/presence_router_callbacks.html">Presence router callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_validity_callbacks.html">Account validity callbacks</a></li><li class="chapter-item expanded "><a href="modules/porting_legacy_module.html">Porting a legacy module to the new interface</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/registration_tokens.html">Registration Tokens</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="development/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li class="chapter-item expanded "><a href="opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><a href="development/experimental_features.html">Experimental features</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="replication.html">Replication</a></li><li class="chapter-item expanded "><a href="tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="development/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><a href="development/room-dag-concepts.html">Room DAG concepts</a></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="deprecation_policy.html">Dependency Deprecation Policy</a></li></ol>
             </div>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
         </nav>
@@ -197,13 +197,118 @@ that your email address is probably <code>user@example.com</code> rather than
 <code>user@email.example.com</code>) - but doing so may require more advanced setup: see
 <a href="setup/../federate.html">Setting up Federation</a>.</p>
 <h2 id="installing-synapse"><a class="header" href="#installing-synapse">Installing Synapse</a></h2>
-<h3 id="installing-from-source"><a class="header" href="#installing-from-source">Installing from source</a></h3>
-<p>(Prebuilt packages are available for some platforms - see <a href="setup/installation.html#prebuilt-packages">Prebuilt packages</a>.)</p>
-<p>When installing from source please make sure that the <a href="setup/installation.html#platform-specific-prerequisites">Platform-specific prerequisites</a> are already installed.</p>
+<h3 id="prebuilt-packages"><a class="header" href="#prebuilt-packages">Prebuilt packages</a></h3>
+<p>Prebuilt packages are available for a number of platforms. These are recommended
+for most users.</p>
+<h4 id="docker-images-and-ansible-playbooks"><a class="header" href="#docker-images-and-ansible-playbooks">Docker images and Ansible playbooks</a></h4>
+<p>There is an official synapse image available at
+<a href="https://hub.docker.com/r/matrixdotorg/synapse">https://hub.docker.com/r/matrixdotorg/synapse</a> which can be used with
+the docker-compose file available at
+<a href="https://github.com/matrix-org/synapse/tree/develop/contrib/docker">contrib/docker</a>.
+Further information on this including configuration options is available in the README
+on hub.docker.com.</p>
+<p>Alternatively, Andreas Peters (previously Silvio Fricke) has contributed a
+Dockerfile to automate a synapse server in a single Docker image, at
+<a href="https://hub.docker.com/r/avhost/docker-matrix/tags/">https://hub.docker.com/r/avhost/docker-matrix/tags/</a></p>
+<p>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,
+ma1sd, SSL support, etc.).
+For more details, see
+<a href="https://github.com/spantaleev/matrix-docker-ansible-deploy">https://github.com/spantaleev/matrix-docker-ansible-deploy</a></p>
+<h4 id="debianubuntu"><a class="header" href="#debianubuntu">Debian/Ubuntu</a></h4>
+<h5 id="matrixorg-packages"><a class="header" href="#matrixorg-packages">Matrix.org packages</a></h5>
+<p>Matrix.org provides Debian/Ubuntu packages of Synapse, for the amd64
+architecture via <a href="https://packages.matrix.org/debian/">https://packages.matrix.org/debian/</a>.</p>
+<p>To install the latest release:</p>
+<pre><code class="language-sh">sudo apt install -y lsb-release wget apt-transport-https
+sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
+echo &quot;deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main&quot; |
+    sudo tee /etc/apt/sources.list.d/matrix-org.list
+sudo apt update
+sudo apt install matrix-synapse-py3
+</code></pre>
+<p>Packages are also published for release candidates. To enable the prerelease
+channel, add <code>prerelease</code> to the <code>sources.list</code> line. For example:</p>
+<pre><code class="language-sh">sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
+echo &quot;deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main prerelease&quot; |
+    sudo tee /etc/apt/sources.list.d/matrix-org.list
+sudo apt update
+sudo apt install matrix-synapse-py3
+</code></pre>
+<p>The fingerprint of the repository signing key (as shown by <code>gpg /usr/share/keyrings/matrix-org-archive-keyring.gpg</code>) is
+<code>AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058</code>.</p>
+<h5 id="downstream-debian-packages"><a class="header" href="#downstream-debian-packages">Downstream Debian packages</a></h5>
+<p>We do not recommend using the packages from the default Debian <code>buster</code>
+repository at this time, as they are old and suffer from known security
+vulnerabilities. You can install the latest version of Synapse from
+<a href="setup/installation.html#matrixorg-packages">our repository</a> or from <code>buster-backports</code>. Please
+see the <a href="https://backports.debian.org/Instructions/">Debian documentation</a>
+for information on how to use backports.</p>
+<p>If you are using Debian <code>sid</code> or testing, Synapse is available in the default
+repositories and it should be possible to install it simply with:</p>
+<pre><code class="language-sh">sudo apt install matrix-synapse
+</code></pre>
+<h5 id="downstream-ubuntu-packages"><a class="header" href="#downstream-ubuntu-packages">Downstream Ubuntu packages</a></h5>
+<p>We do not recommend using the packages in the default Ubuntu repository
+at this time, as they are old and suffer from known security vulnerabilities.
+The latest version of Synapse can be installed from <a href="setup/installation.html#matrixorg-packages">our repository</a>.</p>
+<h4 id="fedora"><a class="header" href="#fedora">Fedora</a></h4>
+<p>Synapse is in the Fedora repositories as <code>matrix-synapse</code>:</p>
+<pre><code class="language-sh">sudo dnf install matrix-synapse
+</code></pre>
+<p>Oleg Girko provides Fedora RPMs at
+<a href="https://obs.infoserver.lv/project/monitor/matrix-synapse">https://obs.infoserver.lv/project/monitor/matrix-synapse</a></p>
+<h4 id="opensuse"><a class="header" href="#opensuse">OpenSUSE</a></h4>
+<p>Synapse is in the OpenSUSE repositories as <code>matrix-synapse</code>:</p>
+<pre><code class="language-sh">sudo zypper install matrix-synapse
+</code></pre>
+<h4 id="suse-linux-enterprise-server"><a class="header" href="#suse-linux-enterprise-server">SUSE Linux Enterprise Server</a></h4>
+<p>Unofficial package are built for SLES 15 in the openSUSE:Backports:SLE-15 repository at
+<a href="https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/">https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/</a></p>
+<h4 id="archlinux"><a class="header" href="#archlinux">ArchLinux</a></h4>
+<p>The quickest way to get up and running with ArchLinux is probably with the community package
+<a href="https://www.archlinux.org/packages/community/any/matrix-synapse/">https://www.archlinux.org/packages/community/any/matrix-synapse/</a>, which should pull in most of
+the necessary dependencies.</p>
+<p>pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):</p>
+<pre><code class="language-sh">sudo pip install --upgrade pip
+</code></pre>
+<p>If you encounter an error with lib bcrypt causing an Wrong ELF Class:
+ELFCLASS32 (x64 Systems), you may need to reinstall py-bcrypt to correctly
+compile it under the right architecture. (This should not be needed if
+installing under virtualenv):</p>
+<pre><code class="language-sh">sudo pip uninstall py-bcrypt
+sudo pip install py-bcrypt
+</code></pre>
+<h4 id="void-linux"><a class="header" href="#void-linux">Void Linux</a></h4>
+<p>Synapse can be found in the void repositories as 'synapse':</p>
+<pre><code class="language-sh">xbps-install -Su
+xbps-install -S synapse
+</code></pre>
+<h4 id="freebsd"><a class="header" href="#freebsd">FreeBSD</a></h4>
+<p>Synapse can be installed via FreeBSD Ports or Packages contributed by Brendan Molloy from:</p>
+<ul>
+<li>Ports: <code>cd /usr/ports/net-im/py-matrix-synapse &amp;&amp; make install clean</code></li>
+<li>Packages: <code>pkg install py37-matrix-synapse</code></li>
+</ul>
+<h4 id="openbsd"><a class="header" href="#openbsd">OpenBSD</a></h4>
+<p>As of OpenBSD 6.7 Synapse is available as a pre-compiled binary. The filesystem
+underlying the homeserver directory (defaults to <code>/var/synapse</code>) has to be
+mounted with <code>wxallowed</code> (cf. <code>mount(8)</code>), so creating a separate filesystem
+and mounting it to <code>/var/synapse</code> should be taken into consideration.</p>
+<p>Installing Synapse:</p>
+<pre><code class="language-sh">doas pkg_add synapse
+</code></pre>
+<h4 id="nixos"><a class="header" href="#nixos">NixOS</a></h4>
+<p>Robin Lambertz has packaged Synapse for NixOS at:
+<a href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix">https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix</a></p>
+<h3 id="installing-as-a-python-module-from-pypi"><a class="header" href="#installing-as-a-python-module-from-pypi">Installing as a Python module from PyPI</a></h3>
+<p>It's also possible to install Synapse as a Python module from PyPI.</p>
+<p>When following this route please make sure that the <a href="setup/installation.html#platform-specific-prerequisites">Platform-specific prerequisites</a> are already installed.</p>
 <p>System requirements:</p>
 <ul>
 <li>POSIX-compliant system (tested on Linux &amp; OS X)</li>
-<li>Python 3.5.2 or later, up to Python 3.9.</li>
+<li>Python 3.6 or later, up to Python 3.9.</li>
 <li>At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org</li>
 </ul>
 <p>To install the Synapse homeserver run:</p>
@@ -257,7 +362,7 @@ header files for Python C extensions.</p>
                      python3-pip python3-setuptools sqlite3 \
                      libssl-dev virtualenv libjpeg-dev libxslt1-dev
 </code></pre>
-<h5 id="archlinux"><a class="header" href="#archlinux">ArchLinux</a></h5>
+<h5 id="archlinux-1"><a class="header" href="#archlinux-1">ArchLinux</a></h5>
 <p>Installing prerequisites on ArchLinux:</p>
 <pre><code class="language-sh">sudo pacman -S base-devel python python-pip \
                python-setuptools python-virtualenv sqlite3
@@ -283,13 +388,13 @@ via brew and inform <code>pip</code> about it so that <code>psycopg2</code> buil
 export LDFLAGS=&quot;-L/usr/local/opt/openssl/lib&quot;
 export CPPFLAGS=&quot;-I/usr/local/opt/openssl/include&quot;
 </code></pre>
-<h5 id="opensuse"><a class="header" href="#opensuse">OpenSUSE</a></h5>
+<h5 id="opensuse-1"><a class="header" href="#opensuse-1">OpenSUSE</a></h5>
 <p>Installing prerequisites on openSUSE:</p>
 <pre><code class="language-sh">sudo zypper in -t pattern devel_basis
 sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \
                python-devel libffi-devel libopenssl-devel libjpeg62-devel
 </code></pre>
-<h5 id="openbsd"><a class="header" href="#openbsd">OpenBSD</a></h5>
+<h5 id="openbsd-1"><a class="header" href="#openbsd-1">OpenBSD</a></h5>
 <p>A port of Synapse is available under <code>net/synapse</code>. The filesystem
 underlying the homeserver directory (defaults to <code>/var/synapse</code>) has to be
 mounted with <code>wxallowed</code> (cf. <code>mount(8)</code>), so creating a separate filesystem
@@ -319,110 +424,6 @@ Debian, Fedora, or source installation methods. More information about WSL can
 be found at <a href="https://docs.microsoft.com/en-us/windows/wsl/install-win10">https://docs.microsoft.com/en-us/windows/wsl/install-win10</a> for
 Windows 10 and <a href="https://docs.microsoft.com/en-us/windows/wsl/install-on-server">https://docs.microsoft.com/en-us/windows/wsl/install-on-server</a>
 for Windows Server.</p>
-<h3 id="prebuilt-packages"><a class="header" href="#prebuilt-packages">Prebuilt packages</a></h3>
-<p>As an alternative to installing from source, prebuilt packages are available
-for a number of platforms.</p>
-<h4 id="docker-images-and-ansible-playbooks"><a class="header" href="#docker-images-and-ansible-playbooks">Docker images and Ansible playbooks</a></h4>
-<p>There is an official synapse image available at
-<a href="https://hub.docker.com/r/matrixdotorg/synapse">https://hub.docker.com/r/matrixdotorg/synapse</a> which can be used with
-the docker-compose file available at
-<a href="https://github.com/matrix-org/synapse/tree/develop/contrib/docker">contrib/docker</a>.
-Further information on this including configuration options is available in the README
-on hub.docker.com.</p>
-<p>Alternatively, Andreas Peters (previously Silvio Fricke) has contributed a
-Dockerfile to automate a synapse server in a single Docker image, at
-<a href="https://hub.docker.com/r/avhost/docker-matrix/tags/">https://hub.docker.com/r/avhost/docker-matrix/tags/</a></p>
-<p>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,
-ma1sd, SSL support, etc.).
-For more details, see
-<a href="https://github.com/spantaleev/matrix-docker-ansible-deploy">https://github.com/spantaleev/matrix-docker-ansible-deploy</a></p>
-<h4 id="debianubuntu"><a class="header" href="#debianubuntu">Debian/Ubuntu</a></h4>
-<h5 id="matrixorg-packages"><a class="header" href="#matrixorg-packages">Matrix.org packages</a></h5>
-<p>Matrix.org provides Debian/Ubuntu packages of Synapse via
-<a href="https://packages.matrix.org/debian/">https://packages.matrix.org/debian/</a>.  To install the latest release:</p>
-<pre><code class="language-sh">sudo apt install -y lsb-release wget apt-transport-https
-sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
-echo &quot;deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main&quot; |
-    sudo tee /etc/apt/sources.list.d/matrix-org.list
-sudo apt update
-sudo apt install matrix-synapse-py3
-</code></pre>
-<p>Packages are also published for release candidates. To enable the prerelease
-channel, add <code>prerelease</code> to the <code>sources.list</code> line. For example:</p>
-<pre><code class="language-sh">sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
-echo &quot;deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main prerelease&quot; |
-    sudo tee /etc/apt/sources.list.d/matrix-org.list
-sudo apt update
-sudo apt install matrix-synapse-py3
-</code></pre>
-<p>The fingerprint of the repository signing key (as shown by <code>gpg /usr/share/keyrings/matrix-org-archive-keyring.gpg</code>) is
-<code>AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058</code>.</p>
-<h5 id="downstream-debian-packages"><a class="header" href="#downstream-debian-packages">Downstream Debian packages</a></h5>
-<p>We do not recommend using the packages from the default Debian <code>buster</code>
-repository at this time, as they are old and suffer from known security
-vulnerabilities. You can install the latest version of Synapse from
-<a href="setup/installation.html#matrixorg-packages">our repository</a> or from <code>buster-backports</code>. Please
-see the <a href="https://backports.debian.org/Instructions/">Debian documentation</a>
-for information on how to use backports.</p>
-<p>If you are using Debian <code>sid</code> or testing, Synapse is available in the default
-repositories and it should be possible to install it simply with:</p>
-<pre><code class="language-sh">sudo apt install matrix-synapse
-</code></pre>
-<h5 id="downstream-ubuntu-packages"><a class="header" href="#downstream-ubuntu-packages">Downstream Ubuntu packages</a></h5>
-<p>We do not recommend using the packages in the default Ubuntu repository
-at this time, as they are old and suffer from known security vulnerabilities.
-The latest version of Synapse can be installed from <a href="setup/installation.html#matrixorg-packages">our repository</a>.</p>
-<h4 id="fedora"><a class="header" href="#fedora">Fedora</a></h4>
-<p>Synapse is in the Fedora repositories as <code>matrix-synapse</code>:</p>
-<pre><code class="language-sh">sudo dnf install matrix-synapse
-</code></pre>
-<p>Oleg Girko provides Fedora RPMs at
-<a href="https://obs.infoserver.lv/project/monitor/matrix-synapse">https://obs.infoserver.lv/project/monitor/matrix-synapse</a></p>
-<h4 id="opensuse-1"><a class="header" href="#opensuse-1">OpenSUSE</a></h4>
-<p>Synapse is in the OpenSUSE repositories as <code>matrix-synapse</code>:</p>
-<pre><code class="language-sh">sudo zypper install matrix-synapse
-</code></pre>
-<h4 id="suse-linux-enterprise-server"><a class="header" href="#suse-linux-enterprise-server">SUSE Linux Enterprise Server</a></h4>
-<p>Unofficial package are built for SLES 15 in the openSUSE:Backports:SLE-15 repository at
-<a href="https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/">https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/</a></p>
-<h4 id="archlinux-1"><a class="header" href="#archlinux-1">ArchLinux</a></h4>
-<p>The quickest way to get up and running with ArchLinux is probably with the community package
-<a href="https://www.archlinux.org/packages/community/any/matrix-synapse/">https://www.archlinux.org/packages/community/any/matrix-synapse/</a>, which should pull in most of
-the necessary dependencies.</p>
-<p>pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):</p>
-<pre><code class="language-sh">sudo pip install --upgrade pip
-</code></pre>
-<p>If you encounter an error with lib bcrypt causing an Wrong ELF Class:
-ELFCLASS32 (x64 Systems), you may need to reinstall py-bcrypt to correctly
-compile it under the right architecture. (This should not be needed if
-installing under virtualenv):</p>
-<pre><code class="language-sh">sudo pip uninstall py-bcrypt
-sudo pip install py-bcrypt
-</code></pre>
-<h4 id="void-linux"><a class="header" href="#void-linux">Void Linux</a></h4>
-<p>Synapse can be found in the void repositories as 'synapse':</p>
-<pre><code class="language-sh">xbps-install -Su
-xbps-install -S synapse
-</code></pre>
-<h4 id="freebsd"><a class="header" href="#freebsd">FreeBSD</a></h4>
-<p>Synapse can be installed via FreeBSD Ports or Packages contributed by Brendan Molloy from:</p>
-<ul>
-<li>Ports: <code>cd /usr/ports/net-im/py-matrix-synapse &amp;&amp; make install clean</code></li>
-<li>Packages: <code>pkg install py37-matrix-synapse</code></li>
-</ul>
-<h4 id="openbsd-1"><a class="header" href="#openbsd-1">OpenBSD</a></h4>
-<p>As of OpenBSD 6.7 Synapse is available as a pre-compiled binary. The filesystem
-underlying the homeserver directory (defaults to <code>/var/synapse</code>) has to be
-mounted with <code>wxallowed</code> (cf. <code>mount(8)</code>), so creating a separate filesystem
-and mounting it to <code>/var/synapse</code> should be taken into consideration.</p>
-<p>Installing Synapse:</p>
-<pre><code class="language-sh">doas pkg_add synapse
-</code></pre>
-<h4 id="nixos"><a class="header" href="#nixos">NixOS</a></h4>
-<p>Robin Lambertz has packaged Synapse for NixOS at:
-<a href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix">https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix</a></p>
 <h2 id="setting-up-synapse"><a class="header" href="#setting-up-synapse">Setting up Synapse</a></h2>
 <p>Once you have installed synapse as above, you will need to configure it.</p>
 <h3 id="using-postgresql"><a class="header" href="#using-postgresql">Using PostgreSQL</a></h3>
@@ -1487,6 +1488,11 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
 </code></pre>
 </li>
 </ul>
+<h1 id="upgrading-to-v1440"><a class="header" href="#upgrading-to-v1440">Upgrading to v1.44.0</a></h1>
+<h2 id="the-url-preview-cache-is-no-longer-mirrored-to-storage-providers"><a class="header" href="#the-url-preview-cache-is-no-longer-mirrored-to-storage-providers">The URL preview cache is no longer mirrored to storage providers</a></h2>
+<p>The <code>url_cache/</code> and <code>url_cache_thumbnails/</code> directories in the media store are
+no longer mirrored to storage providers. These two directories can be safely
+deleted from any configured storage providers to reclaim space.</p>
 <h1 id="upgrading-to-v1430"><a class="header" href="#upgrading-to-v1430">Upgrading to v1.43.0</a></h1>
 <h2 id="the-spaces-summary-apis-can-now-be-handled-by-workers"><a class="header" href="#the-spaces-summary-apis-can-now-be-handled-by-workers">The spaces summary APIs can now be handled by workers</a></h2>
 <p>The <a href="https://matrix-org.github.io/synapse/latest/workers.html#available-worker-applications">available worker applications documentation</a>
@@ -5307,12 +5313,16 @@ user_directory:
     #enabled: false
 
     # Defines whether to search all users visible to your HS when searching
-    # the user directory, rather than limiting to users visible in public
-    # rooms. Defaults to false.
+    # the user directory. If false, search results will only contain users
+    # visible in public rooms and users sharing a room with the requester.
+    # Defaults to false.
     #
-    # If you set it true, you'll have to rebuild the user_directory search
-    # indexes, see:
-    # https://matrix-org.github.io/synapse/latest/user_directory.html
+    # NB. If you set this to true, and the last time the user_directory search
+    # indexes were (re)built was before Synapse 1.44, you'll have to
+    # rebuild the indexes in order to search through all known users.
+    # These indexes are built the first time Synapse starts; admins can
+    # manually trigger a rebuild following the instructions at
+    #     https://matrix-org.github.io/synapse/latest/user_directory.html
     #
     # Uncomment to return search results containing all known users, even if that
     # user does not share a room with the requester.
@@ -7300,12 +7310,10 @@ is also used to de-duplicate processing of multiple in-flight requests at once.)
 <ol>
 <li>Checks the database cache by URL and timestamp and returns the result if it
 has not expired and was successful (a 2xx return code).</li>
-<li>Checks if the URL matches an oEmbed pattern. If it does, fetch the oEmbed
-response. If this is an image, replace the URL to fetch and continue. If
-if it is HTML content, use the HTML as the document and continue.</li>
-<li>If it doesn't match an oEmbed pattern, downloads the URL and stores it
-into a file via the media storage provider and saves the local media
-metadata.</li>
+<li>Checks if the URL matches an <a href="https://oembed.com/">oEmbed</a> pattern. If it
+does, update the URL to download.</li>
+<li>Downloads the URL and stores it into a file via the media storage provider
+and saves the local media metadata.</li>
 <li>If the media is an image:
 <ol>
 <li>Generates thumbnails.</li>
@@ -7326,6 +7334,19 @@ provider and saves the local media metadata.</li>
 </li>
 </ol>
 </li>
+<li>If the media is JSON and an oEmbed URL was found:
+<ol>
+<li>Convert the oEmbed response to an Open Graph response.</li>
+<li>If a thumbnail or image is in the oEmbed response:
+<ol>
+<li>Downloads the URL and stores it into a file via the media storage
+provider and saves the local media metadata.</li>
+<li>Generates thumbnails.</li>
+<li>Updates the Open Graph response based on image properties.</li>
+</ol>
+</li>
+</ol>
+</li>
 <li>Stores the result in the database cache.</li>
 </ol>
 </li>
@@ -7645,6 +7666,27 @@ represented by their Matrix user ID (e.g. <code>@alice:example.com</code>).</p>
 </code></pre>
 <p>Called when processing a room creation request. The module must return a <code>bool</code> indicating
 whether the given user (represented by their Matrix user ID) is allowed to create a room.</p>
+<h3 id="user_may_create_room_with_invites"><a class="header" href="#user_may_create_room_with_invites"><code>user_may_create_room_with_invites</code></a></h3>
+<pre><code class="language-python">async def user_may_create_room_with_invites(
+    user: str,
+    invites: List[str],
+    threepid_invites: List[Dict[str, str]],
+) -&gt; bool
+</code></pre>
+<p>Called when processing a room creation request (right after <code>user_may_create_room</code>).
+The module is given the Matrix user ID of the user trying to create a room, as well as a
+list of Matrix users to invite and a list of third-party identifiers (3PID, e.g. email
+addresses) to invite.</p>
+<p>An invited Matrix user to invite is represented by their Matrix user IDs, and an invited
+3PIDs is represented by a dict that includes the 3PID medium (e.g. &quot;email&quot;) through its
+<code>medium</code> key and its address (e.g. &quot;alice@example.com&quot;) through its <code>address</code> key.</p>
+<p>See <a href="https://matrix.org/docs/spec/appendices#pid-types">the Matrix specification</a> for more
+information regarding third-party identifiers.</p>
+<p>If no invite and/or 3PID invite were specified in the room creation request, the
+corresponding list(s) will be empty.</p>
+<p><strong>Note</strong>: This callback is not called when a room is cloned (e.g. during a room upgrade)
+since no invites are sent when cloning a room. To cover this case, modules also need to
+implement <code>user_may_create_room</code>.</p>
 <h3 id="user_may_create_room_alias"><a class="header" href="#user_may_create_room_alias"><code>user_may_create_room_alias</code></a></h3>
 <pre><code class="language-python">async def user_may_create_room_alias(user: str, room_alias: &quot;synapse.types.RoomAlias&quot;) -&gt; bool
 </code></pre>
@@ -7720,9 +7762,9 @@ class IsUserEvilResource(Resource):
         self.evil_users = config.get(&quot;evil_users&quot;) or []
 
     def render_GET(self, request: Request):
-        user = request.args.get(b&quot;user&quot;)[0]
+        user = request.args.get(b&quot;user&quot;)[0].decode()
         request.setHeader(b&quot;Content-Type&quot;, b&quot;application/json&quot;)
-        return json.dumps({&quot;evil&quot;: user in self.evil_users})
+        return json.dumps({&quot;evil&quot;: user in self.evil_users}).encode()
 
 
 class ListSpamChecker:
@@ -11445,6 +11487,41 @@ trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_i
 <p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>:</p>
 <pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG trial tests
 </code></pre>
+<h3 id="running-tests-under-postgresql"><a class="header" href="#running-tests-under-postgresql">Running tests under PostgreSQL</a></h3>
+<p>Invoking <code>trial</code> as above will use an in-memory SQLite database. This is great for
+quick development and testing. However, we recommend using a PostgreSQL database
+in production (and indeed, we have some code paths specific to each database).
+This means that we need to run our unit tests against PostgreSQL too. Our CI does
+this automatically for pull requests and release candidates, but it's sometimes
+useful to reproduce this locally.</p>
+<p>To do so, <a href="development/../postgres.html">configure Postgres</a> and run <code>trial</code> with the
+following environment variables matching your configuration:</p>
+<ul>
+<li><code>SYNAPSE_POSTGRES</code> to anything nonempty</li>
+<li><code>SYNAPSE_POSTGRES_HOST</code></li>
+<li><code>SYNAPSE_POSTGRES_USER</code></li>
+<li><code>SYNAPSE_POSTGRES_PASSWORD</code></li>
+</ul>
+<p>For example:</p>
+<pre><code class="language-shell">export SYNAPSE_POSTGRES=1
+export SYNAPSE_POSTGRES_HOST=localhost
+export SYNAPSE_POSTGRES_USER=postgres
+export SYNAPSE_POSTGRES_PASSWORD=mydevenvpassword
+trial
+</code></pre>
+<h4 id="prebuilt-container"><a class="header" href="#prebuilt-container">Prebuilt container</a></h4>
+<p>Since configuring PostgreSQL can be fiddly, we can make use of a pre-made
+Docker container to set up PostgreSQL and run our tests for us. To do so, run</p>
+<pre><code class="language-shell">scripts-dev/test_postgresql.sh
+</code></pre>
+<p>Any extra arguments to the script will be passed to <code>tox</code> and then to <code>trial</code>,
+so we can run a specific test in this container with e.g.</p>
+<pre><code class="language-shell">scripts-dev/test_postgresql.sh tests.replication.test_sharded_event_persister.EventPersisterShardTestCase
+</code></pre>
+<p>The container creates a folder in your Synapse checkout called
+<code>.tox-pg-container</code> and uses this as a tox environment. The output of any
+<code>trial</code> runs goes into <code>_trial_temp</code> in your synapse source directory — the same
+as running <code>trial</code> directly on your host machine.</p>
 <h2 id="run-the-integration-tests-a-hrefhttpsgithubcommatrix-orgsytestsytesta"><a class="header" href="#run-the-integration-tests-a-hrefhttpsgithubcommatrix-orgsytestsytesta">Run the integration tests (<a href="https://github.com/matrix-org/sytest">Sytest</a>).</a></h2>
 <p>The integration tests are a more comprehensive suite of tests. They
 run a full version of Synapse, including your changes, to check if
@@ -12142,6 +12219,39 @@ default value is the <strong>string</strong> <code>&quot;FALSE&quot;</code> - wh
 in Python, evaluates to <code>True</code>.</p>
 </li>
 </ul>
+<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="implementing-experimental-features-in-synapse"><a class="header" href="#implementing-experimental-features-in-synapse">Implementing experimental features in Synapse</a></h1>
+<p>It can be desirable to implement &quot;experimental&quot; features which are disabled by
+default and must be explicitly enabled via the Synapse configuration. This is
+applicable for features which:</p>
+<ul>
+<li>Are unstable in the Matrix spec (e.g. those defined by an MSC that has not yet been merged).</li>
+<li>Developers are not confident in their use by general Synapse administrators/users
+(e.g. a feature is incomplete, buggy, performs poorly, or needs further testing).</li>
+</ul>
+<p>Note that this only really applies to features which are expected to be desirable
+to a broad audience. The <a href="development/../modules/index.html">module infrastructure</a> should
+instead be investigated for non-standard features.</p>
+<p>Guarding experimental features behind configuration flags should help with some
+of the following scenarios:</p>
+<ul>
+<li>Ensure that clients do not assume that unstable features exist (failing
+gracefully if they do not).</li>
+<li>Unstable features do not become de-facto standards and can be removed
+aggressively (since only those who have opted-in will be affected).</li>
+<li>Ease finding the implementation of unstable features in Synapse (for future
+removal or stabilization).</li>
+<li>Ease testing a feature (or removal of feature) due to enabling/disabling without
+code changes. It also becomes possible to ask for wider testing, if desired.</li>
+</ul>
+<p>Experimental configuration flags should be disabled by default (requiring Synapse
+administrators to explicitly opt-in), although there are situations where it makes
+sense (from a product point-of-view) to enable features by default. This is
+expected and not an issue.</p>
+<p>It is not a requirement for experimental features to be behind a configuration flag,
+but one should be used if unsure.</p>
+<p>New experimental configuration flags should be added under the <code>experimental</code>
+configuration key (see the <code>synapse.config.experimental</code> file) and either explain
+(briefly) what is being enabled, or include the MSC number.</p>
 <div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="log-contexts"><a class="header" href="#log-contexts">Log Contexts</a></h1>
 <p>To help track the processing of individual requests, synapse uses a
 '<code>log context</code>' to track which request it is handling at any given