diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 137 |
1 files changed, 108 insertions, 29 deletions
diff --git a/README.rst b/README.rst index c58ebf0dbe..ce0d51036e 100644 --- a/README.rst +++ b/README.rst @@ -1,16 +1,18 @@ About ===== -Matrix is an ambitious new ecosystem for open federated Instant Messaging and VoIP[1]. +Matrix is an ambitious new ecosystem for open federated Instant Messaging and +VoIP[1]. -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 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 + - 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 +20,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,16 +40,56 @@ 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 - +.. [1] VoIP currently in development +.. [2] Cryptographic signing of messages isn't turned on yet +.. [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 =================== @@ -58,10 +100,10 @@ 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 + │ ├── 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 @@ -82,13 +124,12 @@ Directory Structure └── webclient Basic AngularJS Matrix web client -Installation -============ +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 +143,12 @@ 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 This will run a process of downloading and installing into your user's .local/lib directory all of the required dependencies that are @@ -161,6 +208,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 point a demo webclient at, simply run:: + + $ demo/start.sh Running The Demo Web Client =========================== @@ -200,19 +255,43 @@ 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. + +Identity Servers +================ -Building Documentation +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. + + +How does it all work?! ====================== -Before building documentation install spinx and sphinxcontrib-napoleon:: +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 |