general clean up. s/alpha/beta/g. add intelfx's AUR package for Arch. s/the homeserver/Synapse/g. move installation & running sections closer together.

This commit is contained in:
Matthew Hodgson 2015-04-29 00:00:24 +01:00
parent cc52f02d74
commit cc5d68f4c4

View file

@ -20,7 +20,7 @@ The overall architecture is::
https://somewhere.org/_matrix https://elsewhere.net/_matrix https://somewhere.org/_matrix https://elsewhere.net/_matrix
``#matrix:matrix.org`` is the official support room for Matrix, and can be ``#matrix:matrix.org`` is the official support room for Matrix, and can be
accessed by the web client at http://matrix.org/alpha or via an IRC bridge at accessed by the web client at http://matrix.org/beta or via an IRC bridge at
irc://irc.freenode.net/matrix. irc://irc.freenode.net/matrix.
Synapse is currently in rapid development, but as of version 0.5 we believe it Synapse is currently in rapid development, but as of version 0.5 we believe it
@ -69,21 +69,27 @@ Synapse ships with two basic demo Matrix clients: webclient (a basic group chat
web client demo implemented in AngularJS) and cmdclient (a basic Python web client demo implemented in AngularJS) and cmdclient (a basic Python
command line utility which lets you easily see what the JSON APIs are up to). command line utility which lets you easily see what the JSON APIs are up to).
Meanwhile, iOS and Android SDKs and clients are currently in development and available from: Meanwhile, iOS and Android SDKs and clients are available from:
- https://github.com/matrix-org/matrix-ios-sdk - https://github.com/matrix-org/matrix-ios-sdk
- https://github.com/matrix-org/matrix-ios-kit
- https://github.com/matrix-org/matrix-ios-console
- https://github.com/matrix-org/matrix-android-sdk - https://github.com/matrix-org/matrix-android-sdk
We'd like to invite you to join #matrix:matrix.org (via http://matrix.org/alpha), run a homeserver, take a look at the Matrix spec at We'd like to invite you to join #matrix:matrix.org (via
http://matrix.org/docs/spec, experiment with the APIs and the demo https://matrix.org/beta), run a homeserver, take a look at the Matrix spec at
clients, and report any bugs via http://matrix.org/jira. https://matrix.org/docs/spec and API docs at https://matrix.org/docs/api,
experiment with the APIs and the demo clients, and report any bugs via
https://matrix.org/jira.
Thanks for using Matrix! Thanks for using Matrix!
[1] End-to-end encryption is currently in development [1] End-to-end encryption is currently in development
Homeserver Installation Synapse Installation
======================= ====================
Synapse is the reference python/twisted Matrix homeserver implementation.
System requirements: System requirements:
- POSIX-compliant system (tested on Linux & OS X) - POSIX-compliant system (tested on Linux & OS X)
@ -152,36 +158,51 @@ you can use the command line to register new users::
For reliable VoIP calls to be routed via this homeserver, you MUST configure For reliable VoIP calls to be routed via this homeserver, you MUST configure
a TURN server. See docs/turn-howto.rst for details. a TURN server. See docs/turn-howto.rst for details.
Troubleshooting Installation Using PostgreSQL
---------------------------- ================
Synapse requires pip 1.7 or later, so if your OS provides too old a version and As of Synapse 0.9, `PostgreSQL <http://www.postgresql.org>`_ is supported as an
you get errors about ``error: no such option: --process-dependency-links`` you alternative to the `SQLite <http://sqlite.org/>`_ database that Synapse has
may need to manually upgrade it:: traditionally used for convenience and simplicity.
$ sudo pip install --upgrade pip The advantages of Postgres include:
If pip crashes mid-installation for reason (e.g. lost terminal), pip may * significant performance improvements due to the superior threading and
refuse to run until you remove the temporary installation directory it caching model, smarter query optimiser
created. To reset the installation:: * allowing the DB to be run on separate hardware
* allowing basic active/backup high-availability with a "hot spare" synapse
pointing at the same DB master, as well as enabling DB replication in
synapse itself.
The only disadvantage is that the code is relatively new as of April 2015 and
may have a few regressions relative to SQLite.
$ rm -rf /tmp/pip_install_matrix For information on how to install and use PostgreSQL, please see
`docs/postgres.rst <docs/postgres.rst>`_.
pip seems to leak *lots* of memory during installation. For instance, a Linux Running Synapse
host with 512MB of RAM may run out of memory whilst installing Twisted. If this ===============
happens, you will have to individually install the dependencies which are
failing, e.g.::
$ pip install twisted To actually run your new homeserver, pick a working directory for Synapse to run
(e.g. ``~/.synapse``), and::
On OSX, if you encounter clang: error: unknown argument: '-mno-fused-madd' you $ cd ~/.synapse
will need to export CFLAGS=-Qunused-arguments. $ source ./bin/activate
$ synctl start
Platform Specific Instructions
==============================
ArchLinux ArchLinux
--------- ---------
Installation on ArchLinux may encounter a few hiccups as Arch defaults to The quickest way to get up and running with ArchLinux is probably with Ivan
python 3, but synapse currently assumes python 2.7 by default. Shapovalov's AUR package from
https://aur.archlinux.org/packages/matrix-synapse/, which should pull in all
the necessary dependencies.
Alternatively, to install using pip a few changes may be needed as ArchLinux
defaults to python 3, but synapse currently assumes python 2.7 by default:
pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):: pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 )::
@ -201,7 +222,7 @@ installing under virtualenv)::
$ sudo pip2.7 uninstall py-bcrypt $ sudo pip2.7 uninstall py-bcrypt
$ sudo pip2.7 install py-bcrypt $ sudo pip2.7 install py-bcrypt
During setup of homeserver you need to call python2.7 directly again:: During setup of Synapse you need to call python2.7 directly again::
$ cd ~/.synapse $ cd ~/.synapse
$ python2.7 -m synapse.app.homeserver \ $ python2.7 -m synapse.app.homeserver \
@ -242,15 +263,33 @@ Troubleshooting:
you do, you may need to create a symlink to ``libsodium.a`` so ``ld`` can find you do, you may need to create a symlink to ``libsodium.a`` so ``ld`` can find
it: ``ln -s /usr/local/lib/libsodium.a /usr/lib/libsodium.a`` it: ``ln -s /usr/local/lib/libsodium.a /usr/lib/libsodium.a``
Running Your Homeserver Troubleshooting
======================= ===============
To actually run your new homeserver, pick a working directory for Synapse to run Troubleshooting Installation
(e.g. ``~/.synapse``), and:: ----------------------------
$ cd ~/.synapse Synapse requires pip 1.7 or later, so if your OS provides too old a version and
$ source ./bin/activate you get errors about ``error: no such option: --process-dependency-links`` you
$ synctl start may need to manually upgrade it::
$ sudo pip install --upgrade pip
If pip crashes mid-installation for reason (e.g. lost terminal), pip may
refuse to run until you remove the temporary installation directory it
created. To reset the installation::
$ rm -rf /tmp/pip_install_matrix
pip seems to leak *lots* of memory during installation. For instance, a Linux
host with 512MB of RAM may run out of memory whilst installing Twisted. If this
happens, you will have to individually install the dependencies which are
failing, e.g.::
$ pip install twisted
On OSX, if you encounter clang: error: unknown argument: '-mno-fused-madd' you
will need to export CFLAGS=-Qunused-arguments.
Troubleshooting Running Troubleshooting Running
----------------------- -----------------------
@ -271,7 +310,7 @@ fix try re-installing from PyPI or directly from
$ pip install --user https://github.com/pyca/pynacl/tarball/master $ pip install --user https://github.com/pyca/pynacl/tarball/master
ArchLinux ArchLinux
--------- ~~~~~~~~~
If running `$ synctl start` fails with 'returned non-zero exit status 1', If running `$ synctl start` fails with 'returned non-zero exit status 1',
you will need to explicitly call Python2.7 - either running as:: you will need to explicitly call Python2.7 - either running as::
@ -280,16 +319,16 @@ you will need to explicitly call Python2.7 - either running as::
...or by editing synctl with the correct python executable. ...or by editing synctl with the correct python executable.
Homeserver Development Synapse Development
====================== ===================
To check out a homeserver for development, clone the git repo into a working To check out a synapse for development, clone the git repo into a working
directory of your choice:: directory of your choice::
$ git clone https://github.com/matrix-org/synapse.git $ git clone https://github.com/matrix-org/synapse.git
$ cd synapse $ cd synapse
The homeserver has a number of external dependencies, that are easiest Synapse has a number of external dependencies, that are easiest
to install using pip and a virtualenv:: to install using pip and a virtualenv::
$ virtualenv env $ virtualenv env
@ -300,7 +339,7 @@ to install using pip and a virtualenv::
This will run a process of downloading and installing all the needed This will run a process of downloading and installing all the needed
dependencies into a virtual env. dependencies into a virtual env.
Once this is done, you may wish to run the homeserver's unit tests, to Once this is done, you may wish to run Synapse's unit tests, to
check that everything is installed as it should be:: check that everything is installed as it should be::
$ python setup.py test $ python setup.py test
@ -312,10 +351,10 @@ This should end with a 'PASSED' result::
PASSED (successes=143) PASSED (successes=143)
Upgrading an existing homeserver Upgrading an existing Synapse
================================ =============================
IMPORTANT: Before upgrading an existing homeserver to a new version, please IMPORTANT: Before upgrading an existing synapse to a new version, please
refer to UPGRADE.rst for any additional instructions. refer to UPGRADE.rst for any additional instructions.
Otherwise, simply re-install the new codebase over the current one - e.g. Otherwise, simply re-install the new codebase over the current one - e.g.
@ -376,8 +415,8 @@ SRV record, as that is the name other machines will expect it to have::
You may additionally want to pass one or more "-v" options, in order to You may additionally want to pass one or more "-v" options, in order to
increase the verbosity of logging output; at least for initial testing. increase the verbosity of logging output; at least for initial testing.
Running a Demo Federation of Homeservers Running a Demo Federation of Synapses
---------------------------------------- -------------------------------------
If you want to get up and running quickly with a trio of homeservers in a If you want to get up and running quickly with a trio of homeservers in a
private federation (``localhost:8080``, ``localhost:8081`` and private federation (``localhost:8080``, ``localhost:8081`` and
@ -412,7 +451,10 @@ account. Your name will take the form of::
Specify your desired localpart in the topmost box of the "Register for an Specify your desired localpart in the topmost box of the "Register for an
account" form, and click the "Register" button. Hostnames can contain ports if account" form, and click the "Register" button. Hostnames can contain ports if
required due to lack of SRV records (e.g. @matthew:localhost:8448 on an required due to lack of SRV records (e.g. @matthew:localhost:8448 on an
internal synapse sandbox running on localhost) internal synapse sandbox running on localhost).
If registration fails, you may need to enable it in the homeserver (see
`Synapse Installation`_ above)
Logging In To An Existing Account Logging In To An Existing Account