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

README.rst

@@ -5,7 +5,7 @@ Matrix is an ambitious new ecosystem for open federated Instant Messaging and
 VoIP.  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 
+      can be found using aliases like ``#matrix:matrix.org`` or 
       ``#test:localhost:8008`` or they can be ephemeral.
     
     - Matrix user IDs look like ``@matthew:matrix.org`` (although in the future
@@ -15,27 +15,48 @@ VoIP.  The basics you need to know to get up and running are:
 The overall architecture is::
 
       client <----> homeserver <=====================> homeserver <----> client
-             https://matrix.org/_matrix      https://mydomain.net/_matrix
+             https://somewhere.org/_matrix      https://elsewhere.net/_matrix
+
+WARNING
+=======
+
+**Synapse is currently in a state of rapid development, and not all features are yet functional.
+Critically, some security features are still in development, which means Synapse can *not*
+be considered secure or reliable at this point.**  For instance:
+
+- **SSL Certificates used by server-server federation are not yet validated.**
+- **Room permissions are not yet enforced on traffic received via federation.**
+- **Homeservers do not yet cryptographically sign their events to avoid tampering**
+- Default configuration provides open signup to the service from the internet
+
+Despite this, we believe Synapse is more than useful as a way for experimenting and
+exploring Synapse, and the missing features will land shortly.  **Until then, please do *NOT*
+use Synapse for any remotely important or secure communication.**
+
 
 Quick Start
 ===========
 
+System requirements:
+    - POSIX-compliant system (tested on Linux & OSX)
+    - Python 2.7
+
 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:8008, install synapse 
-      with ``python setup.py develop --user`` and then run one with
-      ``python synapse/app/homeserver.py`` - you will find a webclient running
-      at http://localhost:8008 (use a recent Chrome, Safari or Firefox for now,
-      please...)
+    - To run your own **private** homeserver on localhost:8008, install synapse with
+      ``python setup.py develop --user`` and then run ``./synctl start`` twice (once to
+      generate a config; once to actually run) - you will find a webclient running at
+      http://localhost:8008. Please use a recent Chrome, Safari or Firefox for now...
              
-    - To make the homeserver **public** and let it exchange messages with 
-      other homeservers and participate in the overall Matrix federation, open 
-      up port 8448 and run ``python synapse/app/homeserver.py --host 
-      machine.my.domain.name``.  Then come join ``#matrix:matrix.org`` and
-      say hi! :)
+    - To run a **public** homeserver and let it exchange messages with other homeservers
+      and participate in the global Matrix federation, you must expose port 8448 to the
+      internet and edit homeserver.yaml to specify server_name (the public DNS entry for
+      this server) and then run ``synctl start``. If you changed the server_name, you may
+      need to move the old database (homeserver.db) out of the way first. Then come join
+      ``#matrix:matrix.org`` and say hi! :)
 
 For more detailed setup instructions, please see further down this document.
 
@@ -100,7 +121,6 @@ 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. synapse requires python 2.x where x >= 7
 
   Installing prerequisites on ubuntu::
 
@@ -131,6 +151,9 @@ 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).
 
+On OSX, if you encounter ``clang: error: unknown argument: '-mno-fused-madd'`` you will
+need to ``export CFLAGS=-Qunused-arguments``.
+
 This will run a process of downloading and installing into your
 user's .local/lib directory all of the required dependencies that are
 missing.
@@ -180,6 +203,10 @@ For the first form, simply pass the required hostname (of the machine) as the
         --generate-config
     $ python synapse/app/homeserver.py --config-path homeserver.config
     
+Alternatively, you can run synapse via synctl - running ``synctl start`` to generate a
+homeserver.yaml config file, where you can then edit server-name to specify
+machine.my.domain.name, and then set the actual server running again with synctl start.
+
 For the second form, first create your SRV record and publish it in DNS. This
 needs to be named _matrix._tcp.YOURDOMAIN, and point at at least one hostname
 and port where the server is running.  (At the current time synapse does not
@@ -266,7 +293,7 @@ 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.
+we are running a single identity server (http://matrix.org:8090) at the current time.
 
 
 Where's the spec?!

scripts/gendoc.sh

@@ -7,8 +7,8 @@ rst2html-2.7.py --stylesheet=basic.css,nature.css ../docs/client-server/howto.rs
 
 perl -pi -e 's#<head>#<head><link rel="stylesheet" href="/site.css">#' $MATRIXDOTORG/docs/spec/index.html $MATRIXDOTORG/docs/howtos/client-server.html
 
-perl -pi -e 's#<body>#<body><div id="header"><div id="headerContent">&nbsp;</div></div><div id="page"><div id="wrapper"><div style="text-align: center; padding: 40px;"><img src="/matrix.png" width="305" height="130" alt="[matrix]"/></div>#' $MATRIXDOTORG/docs/spec/index.html $MATRIXDOTORG/docs/howtos/client-server.html
+perl -pi -e 's#<body>#<body><div id="header"><div id="headerContent">&nbsp;</div></div><div id="page"><div id="wrapper"><div style="text-align: center; padding: 40px;"><a href="/"><img src="/matrix.png" width="305" height="130" alt="[matrix]"/></a></div>#' $MATRIXDOTORG/docs/spec/index.html $MATRIXDOTORG/docs/howtos/client-server.html
 
 perl -pi -e 's#</body>#</div></div><div id="footer"><div id="footerContent">&copy 2014 Matrix.org</div></div></body>#' $MATRIXDOTORG/docs/spec/index.html $MATRIXDOTORG/docs/howtos/client-server.html
 
-scp -r $MATRIXDOTORG/docs matrix@ldc-prd-matrix-001:/sites/matrix-beta
+scp -r $MATRIXDOTORG/docs matrix@ldc-prd-matrix-001:/sites/matrix