Merge branch 'master' of github.com:matrix-org/synapse

1 files changed, 54 insertions, 79 deletions

diff --git a/README.rst b/README.rst
index 2885c9f2f2..319bbb6e4e 100644
--- a/README.rst
+++ b/README.rst
@@ -1,16 +1,52 @@
-About
-=====
+Quick Start
+===========
 
 Matrix is an ambitious new ecosystem for open federated Instant Messaging and
-VoIP[1].
+VoIP[1].  The basics you need to know to get up and running are:
+
+    - Chatrooms are distributed and do not exist on any single server.  Rooms 
+      can be found using names like ``#matrix:matrix.org`` or 
+      ``#test:localhost:8080`` or they can be ephemeral.
+    
+    - Matrix user IDs look like ``@matthew:matrix.org`` (although in the future
+      you will normally refer to yourself and others using a 3PID: email
+      address, phone number, etc rather than manipulating matrix user IDs)
 
-Matrix specifies a set of pragmatic RESTful HTTP JSON APIs as an open standard,
-providing:
+The overall architecture is::
+
+      client <----> homeserver <=================> homeserver  <-----> client
+                e.g. matrix.org:8080        e.g. mydomain.net:8080
+
+To get up and running:
+      
+    - To simply play with an **existing** homeserver you can
+      just go straight to http://matrix.org/alpha.
+    
+    - To run your own **private** homeserver on localhost:8080, install synapse 
+      with ``python setup.py develop --user`` and then run one with
+      ``python synapse/app/homeserver.py``
+      
+    - To run your own webclient:
+      ``cd webclient; python -m SimpleHTTPServer`` and hit http://localhost:8000
+      in your web browser (a recent Chrome, Safari or Firefox for now,
+      please...)
+             
+    - To make the homeserver **public** and let it exchange messages with 
+      other homeservers and participate in the overall Matrix federation, open 
+      up port 8080 and run ``python synapse/app/homeserver.py --host 
+      machine.my.domain.name``.  Then come join ``#matrix:matrix.org`` and
+      say hi! :)
+    
+About Matrix
+============
+
+Matrix specifies a set of pragmatic RESTful HTTP JSON APIs for VoIP and IM as an
+open standard, providing:
 
     - Creating and managing fully distributed chat rooms with no
       single points of control or failure
     - Eventually-consistent cryptographically secure[2] synchronisation of room 
-	  state across a global open network of federated servers and services
+      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[3]
     - Inviting, joining, leaving, kicking, banning room members
@@ -57,74 +93,6 @@ Thanks for trying Matrix!
 
 [3] End-to-end encryption is currently in development
 
-Quick Start
-===========
-
-The basics you need to know about Matrix are:
-
-    - Chatrooms look like ``#matrix:matrix.org`` or ``#test:localhost:8080``
-    
-    - Matrix user IDs look like ``@matthew:matrix.org`` (although in the future
-      you will normally refer to yourself and others using a 3PID: email
-      address, phone number, etc rather than manipulating matrix user IDs)
-      
-    - To simply play with an **existing** homeserver (e.g. matrix.org), you can
-      just go straight to http://matrix.org/alpha, specify a homeserver 
-      (defaults to matrix.org) and sign up and use it. (Sign-up security is
-      currently work-in-progress)
-    
-    - To run your own **private** homeserver on localhost:8080, install synapse 
-      with ``python setup.py develop --user`` and then run one with
-      ``python synapse/app/homeserver.py``
-      
-    - To run your own webclient:
-      ``cd webclient; python -m SimpleHTTPServer`` and hit http://localhost:8000
-      in your web browser (a recent Chrome, Safari or Firefox for now,
-      please...)
-       
-    - For now, register some accounts like ``@testing:localhost:8080`` from 
-      different browsers, join a room like ``#test:localhost:8080`` and have a 
-      play.
-      
-    - To quickly run a **public** homeserver that can exchange messages with 
-      other homeservers and participate in the overall Matrix federation, open 
-      up port 8080 and run ``python synapse/app/homeserver.py --host 
-      machine.my.domain.name``.  Then come join ``#matrix:matrix.org`` and
-      say hi! :)
-    
-
-Directory Structure
-===================
-
-::
-
-    .
-    ├── cmdclient           Basic CLI python Matrix client
-    ├── demo                Scripts for running standalone Matrix demos
-    ├── docs                All doc, including the draft Matrix API spec
-    │   ├── client-server       The client-server Matrix API spec
-    │   ├── model               Domain-specific elements of the Matrix API spec
-    │   ├── server-server       The server-server model of the Matrix API spec
-    │   └── sphinx              The internal API doc of the Synapse homeserver
-    ├── experiments         Early experiments of using Synapse's internal APIs
-    ├── graph               Visualisation of Matrix's distributed message store 
-    ├── synapse             The reference Matrix homeserver implementation
-    │   ├── api                 Common building blocks for the APIs
-    │   │   ├── events              Definition of state representation Events 
-    │   │   └── streams             Definition of streamable Event objects
-    │   ├── app                 The __main__ entry point for the homeserver
-    │   ├── crypto              The PKI client/server used for secure federation
-    │   │   └── resource            PKI helper objects (e.g. keys)
-    │   ├── federation          Server-server state replication logic
-    │   ├── handlers            The main business logic of the homeserver
-    │   ├── http                Wrappers around Twisted's HTTP server & client
-    │   ├── rest                Servlet-style RESTful API
-    │   ├── storage             Persistence subsystem (currently only sqlite3)
-    │   │   └── schema              sqlite persistence schema
-    │   └── util                Synapse-specific utilities
-    ├── tests               Unit tests for the Synapse homeserver
-    └── webclient           Basic AngularJS Matrix web client
-
 
 Homeserver Installation
 =======================
@@ -151,6 +119,12 @@ may need to also run:
 
     $ sudo apt-get install python-pip
     $ sudo pip install --upgrade setuptools
+    
+If you get errors about ``sodium.h`` being missing, you may also need to
+manually install a newer PyNaCl via pip as setuptools installs an old one. Or
+you can check PyNaCl out of git directly (https://github.com/pyca/pynacl) and
+installing it. Installing PyNaCl using pip may also work (remember to remove any
+other versions installed by setuputils in, for example, ~/.local/lib).
 
 This will run a process of downloading and installing into your
 user's .local/lib directory all of the required dependencies that are
@@ -168,8 +142,8 @@ This should end with a 'PASSED' result::
     PASSED (successes=143)
 
 
-Running The Synapse Homeserver
-==============================
+Setting up Federation
+=====================
 
 In order for other homeservers to send messages to your server, it will need to
 be publicly visible on the internet, and they will need to know its host name.
@@ -215,7 +189,7 @@ Running a Demo Federation of Homeservers
 
 If you want to get up and running quickly with a trio of homeservers in a
 private federation (``localhost:8080``, ``localhost:8081`` and
-``localhost:8082``) which you can then point a demo webclient at, simply run::
+``localhost:8082``) which you can then access through the webclient running at http://localhost:8080.  Simply run::
 
     $ demo/start.sh
 
@@ -279,8 +253,8 @@ as the primary means of identity and E2E encryption is not complete. As such,
 we're not yet running an identity server in public.
 
 
-How does it all work?!
-======================
+Where's the spec?!
+==================
 
 For now, please go spelunking in the ``docs/`` directory to find out.
 
@@ -297,3 +271,4 @@ sphinxcontrib-napoleon::
 Building internal API documentation::
 
     $ python setup.py build_sphinx
+