diff --git a/README.rst b/README.rst
index c58ebf0dbe..319bbb6e4e 100644
--- a/README.rst
+++ b/README.rst
@@ -1,16 +1,54 @@
-About
-=====
-
-Matrix is an ambitious new ecosystem for open federated Instant Messaging and VoIP[1].
+Quick Start
+===========
+
+Matrix is an ambitious new ecosystem for open federated Instant Messaging and
+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)
+
+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 as an open standard, providing:
+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 synchronisation of room
- state across a global open network of federated servers and services
+ - Eventually-consistent cryptographically secure[2] 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[2]
+ end-to-end encryption[3]
- Inviting, joining, leaving, kicking, banning room members
- Managing user accounts (registration, login, logout)
- Using 3rd Party IDs (3PIDs) such as email addresses, phone numbers,
@@ -18,11 +56,11 @@ Matrix specifies a set of pragmatic RESTful HTTP JSON APIs as an open standard,
- Placing 1:1 VoIP and Video calls (in development)
These APIs are intended to be implemented on a wide range of servers, services
-and clients which then form the Matrix ecosystem, and allow developers to build
-messaging and VoIP functionality on top of the open Matrix community rather than
-using closed or proprietary solutions. The hope is for Matrix to act as the
-building blocks for a new generation of fully open and interoperable messaging
-and VoIP apps for the internet.
+and clients, letting developers build messaging and VoIP functionality on top of
+the entirely open Matrix ecosystem rather than using closed or proprietary
+solutions. The hope is for Matrix to act as the building blocks for a new
+generation of fully open and interoperable messaging and VoIP apps for the
+internet.
Synapse is a reference "homeserver" implementation of Matrix from the core
development team at matrix.org, written in Python/Twisted for clarity and
@@ -38,57 +76,30 @@ control and own your own communications and history or use one hosted by someone
else (e.g. matrix.org) - there is no single point of control or mandatory
service provider in Matrix, unlike WhatsApp, Facebook, Hangouts, etc.
-Synapse ships with two basic demo Matrix clients: webclient (a basic group chat web client demo implemented in AngularJS) and cmdclient (a basic Python commandline utility which lets you easily see what the JSON APIs are up to).
+Synapse ships with two basic demo Matrix clients: webclient (a basic group chat
+web client demo implemented in AngularJS) and cmdclient (a basic Python
+commandline utility which lets you easily see what the JSON APIs are up to).
-We'd like to invite you to take a look at the Matrix spec, try to run a homeserver, and join the existing Matrix chatrooms already out there, experiment with the APIs and the demo clients, and let us know your thoughts at https://github.com/matrix-org/synapse/issues or at matrix@matrix.org.
+We'd like to invite you to take a look at the Matrix spec, try to run a
+homeserver, and join the existing Matrix chatrooms already out there, experiment
+with the APIs and the demo clients, and let us know your thoughts at
+https://github.com/matrix-org/synapse/issues or at matrix@matrix.org.
Thanks for trying Matrix!
[1] VoIP currently in development
-[2] End-to-end encryption is currently in development
-
-
-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
-
-
-Installation
-============
+[2] Cryptographic signing of messages isn't turned on yet
+
+[3] End-to-end encryption is currently in development
+
+
+Homeserver Installation
+=======================
First, the dependencies need to be installed. Start by installing
'python2.7-dev' and the various tools of the compiler toolchain.
-
-N.B. that python 2.x where x >= 7 is required.
+N.B. synapse requires python 2.x where x >= 7
Installing prerequisites on ubuntu::
@@ -102,6 +113,18 @@ The homeserver has a number of external dependencies, that are easiest
to install by making setup.py do so, in --user mode::
$ python setup.py develop --user
+
+You'll need a version of setuptools new enough to know about git, so you
+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
@@ -119,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.
@@ -161,6 +184,14 @@ For the initial alpha release, the homeserver is not speaking TLS for
either client-server or server-server traffic for ease of debugging. We have
also not spent any time yet getting the homeserver to run behind loadbalancers.
+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 access through the webclient running at http://localhost:8080. Simply run::
+
+ $ demo/start.sh
Running The Demo Web Client
===========================
@@ -200,19 +231,44 @@ synapse sandbox running on localhost)
Logging In To An Existing Account
---------------------------------
-[[TODO(paul): It seems the current web client still requests an access_token -
- I suspect this part will need updating before we can point people at how to
- perform e.g. user+password or 3PID authenticated login]]
+Just enter the ``@localpart:my.domain.here`` matrix user ID and password into the form and click the Login button.
-Building Documentation
-======================
+Identity Servers
+================
-Before building documentation install spinx and sphinxcontrib-napoleon::
+The job of authenticating 3PIDs and tracking which 3PIDs are associated with a
+given matrix user is very security-sensitive, as there is obvious risk of spam
+if it is too easy to sign up for Matrix accounts or harvest 3PID data. Meanwhile
+the job of publishing the end-to-end encryption public keys for Matrix users is
+also very security-sensitive for similar reasons.
+
+Therefore the role of managing trusted identity in the Matrix ecosystem is
+farmed out to a cluster of known trusted ecosystem partners, who run 'Matrix
+Identity Servers' such as ``sydent``, whose role is purely to authenticate and
+track 3PID logins and publish end-user public keys.
+
+It's currently early days for identity servers as Matrix is not yet using 3PIDs
+as the primary means of identity and E2E encryption is not complete. As such,
+we're not yet running an identity server in public.
+
+
+Where's the spec?!
+==================
+
+For now, please go spelunking in the ``docs/`` directory to find out.
+
+
+Building Internal API Documentation
+===================================
+
+Before building internal API documentation install spinx and
+sphinxcontrib-napoleon::
$ pip install sphinx
$ pip install sphinxcontrib-napoleon
-Building documentation::
+Building internal API documentation::
$ python setup.py build_sphinx
+
|
