Rearrange the README

Move some bits of the README around. No words were changed in the making of this commit.
7 years ago · cc03f4c58b
--- a/README.rst
+++ b/README.rst
@@ -11,7 +11,7 @@ VoIP.  The basics you need to know to get up and running are:
  like ``#matrix:matrix.org`` or ``#test:localhost:8448``.

 - Matrix user IDs look like ``@matthew:matrix.org`` (although in the future
  you will normally refer to yourself and others using a third party identifier 
  you will normally refer to yourself and others using a third party identifier
  (3PID): email address, phone number, etc rather than manipulating Matrix user IDs)

 The overall architecture is::
@@ -26,6 +26,7 @@ bridge at irc://irc.freenode.net/matrix.
 Synapse is currently in rapid development, but as of version 0.5 we believe it
 is sufficiently stable to be run as an internet-facing service for real usage!


 About Matrix
 ============

@@ -87,6 +88,7 @@ Thanks for using Matrix!

 [1] End-to-end encryption is currently in development - see https://matrix.org/git/olm


 Synapse Installation
 ====================

@@ -156,8 +158,8 @@ In case of problems, please see the _Troubleshooting section below.
 Alternatively, Silvio Fricke has contributed a Dockerfile to automate the
 above in Docker at https://registry.hub.docker.com/u/silviof/docker-matrix/.

 Also, Martin Giess has created an auto-deployment process with vagrant/ansible, 
 tested with VirtualBox/AWS/DigitalOcean - see https://github.com/EMnify/matrix-synapse-auto-deploy 
 Also, Martin Giess has created an auto-deployment process with vagrant/ansible,
 tested with VirtualBox/AWS/DigitalOcean - see https://github.com/EMnify/matrix-synapse-auto-deploy
 for details.

 To set up your homeserver, run (in your virtualenv, as before)::
@@ -195,6 +197,7 @@ you can use the command line to register new users::
 For reliable VoIP calls to be routed via this homeserver, you MUST configure
 a TURN server.  See docs/turn-howto.rst for details.


 Running Synapse
 ===============

@@ -205,6 +208,42 @@ run (e.g. ``~/.synapse``), and::
    source ./bin/activate
    synctl start


 Running The Demo Web Client
 ===========================

 The homeserver runs a web client by default at https://localhost:8448/.

 If this is the first time you have used the client from that browser (it uses
 HTML5 local storage to remember its config), you will need to log in to your
 account. If you don't yet have an account, because you've just started the
 homeserver for the first time, then you'll need to register one.

 Registering A New Account
 -------------------------

 Your new user name will be formed partly from the hostname your server is
 running as, and partly from a localpart you specify when you create the
 account. Your name will take the form of::

    @localpart:my.domain.here
         (pronounced "at localpart on my dot domain dot here")

 Specify your desired localpart in the topmost box of the "Register for an
 account" form, and click the "Register" button. Hostnames can contain ports if
 required due to lack of SRV records (e.g. @matthew:localhost:8448 on an
 internal synapse sandbox running on localhost).

 If registration fails, you may need to enable it in the homeserver (see
 `Synapse Installation`_ above)

 Logging In To An Existing Account
 ---------------------------------

 Just enter the ``@localpart:my.domain.here`` Matrix user ID and password into
 the form and click the Login button.


 Security Note
 =============

@@ -220,24 +259,6 @@ server on the same domain.
 See https://github.com/vector-im/vector-web/issues/1977 and
 https://developer.github.com/changes/2014-04-25-user-content-security for more details.

 Using PostgreSQL
 ================

 As of Synapse 0.9, `PostgreSQL <http://www.postgresql.org>`_ is supported as an
 alternative to the `SQLite <http://sqlite.org/>`_ database that Synapse has
 traditionally used for convenience and simplicity.

 The advantages of Postgres 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.rst <docs/postgres.rst>`_.

 Platform Specific Instructions
 ==============================
@@ -340,6 +361,7 @@ Troubleshooting:
  you do, you may need to create a symlink to ``libsodium.a`` so ``ld`` can find
  it: ``ln -s /usr/local/lib/libsodium.a /usr/lib/libsodium.a``


 Troubleshooting
 ===============

@@ -413,37 +435,6 @@ you will need to explicitly call Python2.7 - either running as::

 ...or by editing synctl with the correct python executable.

 Synapse Development
 ===================

 To check out a synapse for development, clone the git repo into a working
 directory of your choice::

    git clone https://github.com/matrix-org/synapse.git
    cd synapse

 Synapse has a number of external dependencies, that are easiest
 to install using pip and a virtualenv::

    virtualenv env
    source env/bin/activate
    python synapse/python_dependencies.py | xargs -n1 pip install
    pip install setuptools_trial mock

 This will run a process of downloading and installing all the needed
 dependencies into a virtual env.

 Once this is done, you may wish to run Synapse's unit tests, to
 check that everything is installed as it should be::

    python setup.py test

 This should end with a 'PASSED' result::

    Ran 143 tests in 0.601s

    PASSED (successes=143)


 Upgrading an existing Synapse
 =============================
@@ -454,6 +445,7 @@ versions of synapse.

 .. _UPGRADE.rst: UPGRADE.rst


 Setting up Federation
 =====================

@@ -521,41 +513,26 @@ http://localhost:8080. Simply run::

 This is mainly useful just for development purposes.

 Running The Demo Web Client
 ===========================

 The homeserver runs a web client by default at https://localhost:8448/.

 If this is the first time you have used the client from that browser (it uses
 HTML5 local storage to remember its config), you will need to log in to your
 account. If you don't yet have an account, because you've just started the
 homeserver for the first time, then you'll need to register one.


 Registering A New Account

 Your new user name will be formed partly from the hostname your server is
 running as, and partly from a localpart you specify when you create the
 account. Your name will take the form of::

    @localpart:my.domain.here
         (pronounced "at localpart on my dot domain dot here")
 Using PostgreSQL
 ================

 Specify your desired localpart in the topmost box of the "Register for an
 account" form, and click the "Register" button. Hostnames can contain ports if
 required due to lack of SRV records (e.g. @matthew:localhost:8448 on an
 internal synapse sandbox running on localhost).
 As of Synapse 0.9, `PostgreSQL <http://www.postgresql.org>`_ is supported as an
 alternative to the `SQLite <http://sqlite.org/>`_ database that Synapse has
 traditionally used for convenience and simplicity.

 If registration fails, you may need to enable it in the homeserver (see
 `Synapse Installation`_ above)
 The advantages of Postgres 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.

 Logging In To An Existing Account
 For information on how to install and use PostgreSQL, please see
 `docs/postgres.rst <docs/postgres.rst>`_.

 Just enter the ``@localpart:my.domain.here`` Matrix user ID and password into
 the form and click the Login button.

 Identity Servers
 ================
@@ -605,8 +582,8 @@ First calculate the hash of the new password:

    $ source ~/.synapse/bin/activate
    $ ./scripts/hash_password
    Password: 
    Confirm password: 
    Password:
    Confirm password:
    $2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

 Then update the `users` table in the database:
@@ -614,6 +591,7 @@ Then update the `users` table in the database:
    UPDATE users SET password_hash='$2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
        WHERE name='@test:test.com';


 Where's the spec?!
 ==================

@@ -621,6 +599,38 @@ The source of the matrix spec lives at https://github.com/matrix-org/matrix-doc.
 A recent HTML snapshot of this lives at http://matrix.org/docs/spec


 Synapse Development
 ===================

 To check out a synapse for development, clone the git repo into a working
 directory of your choice::

    git clone https://github.com/matrix-org/synapse.git
    cd synapse

 Synapse has a number of external dependencies, that are easiest
 to install using pip and a virtualenv::

    virtualenv env
    source env/bin/activate
    python synapse/python_dependencies.py | xargs -n1 pip install
    pip install setuptools_trial mock

 This will run a process of downloading and installing all the needed
 dependencies into a virtual env.

 Once this is done, you may wish to run Synapse's unit tests, to
 check that everything is installed as it should be::

    python setup.py test

 This should end with a 'PASSED' result::

    Ran 143 tests in 0.601s

    PASSED (successes=143)


 Building Internal API Documentation
 ===================================

@@ -635,7 +645,6 @@ Building internal API documentation::
    python setup.py build_sphinx



 Help!! Synapse eats all my RAM!
 ===============================

@@ -650,4 +659,3 @@ matrix.org on.  The default setting is currently 0.1, which is probably
 around a ~700MB footprint.  You can dial it down further to 0.02 if
 desired, which targets roughly ~512MB.  Conversely you can dial it up if
 you need performance for lots of users and have a box with a lot of RAM.