remove remaining TODOs and fill in lots more info
This commit is contained in:
Matthew Hodgson
parent
286797fc0c
commit
d314315a2e
133
README.rst
133
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
|
||||
.. [1] VoIP currently in development
|
||||
.. [2] Cryptographic signing of messages isn't turned on yet
|
||||
.. [3] End-to-end encryption is currently in development
|
||||
|
||||
[2] 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.
|
||||
|
||||
|
||||
Building Documentation
|
||||
Identity Servers
|
||||
================
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue