diff --git a/README.rst b/README.rst
index e0e835f14f..8f8ba73662 100644
--- 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.
-
|
