diff --git a/README.rst b/README.rst
index 768da3df64..282a53873f 100644
--- a/README.rst
+++ b/README.rst
@@ -95,27 +95,30 @@ Installing prerequisites on Ubuntu or Debian::
$ sudo apt-get install build-essential python2.7-dev libffi-dev \
python-pip python-setuptools sqlite3 \
- libssl-dev
+ libssl-dev python-virtualenv libjpeg-dev
Installing prerequisites on Mac OS X::
$ xcode-select --install
+ $ sudo pip install virtualenv
To install the synapse homeserver run::
- $ pip install --user --process-dependency-links https://github.com/matrix-org/synapse/tarball/master
+ $ virtualenv ~/.synapse
+ $ source ~/.synapse/bin/activate
+ $ pip install --process-dependency-links https://github.com/matrix-org/synapse/tarball/master
-This installs synapse, along with the libraries it uses, into
-``$HOME/.local/lib/`` on Linux or ``$HOME/Library/Python/2.7/lib/`` on OSX.
+This installs synapse, along with the libraries it uses, into a virtual
+environment under ``~/.synapse``.
-Your python may not give priority to locally installed libraries over system
-libraries, in which case you must add your local packages to your python path::
+To set up your homeserver, run (in your virtualenv, as before)::
- $ # on Linux:
- $ export PYTHONPATH=$HOME/.local/lib/python2.7/site-packages:$PYTHONPATH
+ $ python -m synapse.app.homeserver \
+ --server-name machine.my.domain.name \
+ --config-path homeserver.yaml \
+ --generate-config
- $ # on OSX:
- $ export PYTHONPATH=$HOME/Library/Python/2.7/lib/python/site-packages:$PYTHONPATH
+Substituting your host and domain name as appropriate.
For reliable VoIP calls to be routed via this homeserver, you MUST configure
a TURN server. See docs/turn-howto.rst for details.
@@ -128,19 +131,19 @@ you get errors about ``error: no such option: --process-dependency-links`` you
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 --user twisted
+ $ pip install twisted
On OSX, if you encounter clang: error: unknown argument: '-mno-fused-madd' you
will need to export CFLAGS=-Qunused-arguments.
@@ -155,7 +158,7 @@ Synapse can be installed on Cygwin. It requires the following Cygwin packages:
- openssl (and openssl-devel, python-openssl)
- python
- python-setuptools
-
+
The content repository requires additional packages and will be unable to process
uploads without them:
- libjpeg8
@@ -182,23 +185,13 @@ Running Your Homeserver
To actually run your new homeserver, pick a working directory for Synapse to run
(e.g. ``~/.synapse``), and::
- $ mkdir ~/.synapse
$ cd ~/.synapse
-
- $ # on Linux
- $ ~/.local/bin/synctl start
-
- $ # on OSX
- $ ~/Library/Python/2.7/bin/synctl start
+ $ source ./bin/activate
+ $ synctl start
Troubleshooting Running
-----------------------
-If ``synctl`` fails with ``pkg_resources.DistributionNotFound`` errors you may
-need a newer version of setuptools than that provided by your OS.::
-
- $ sudo pip install setuptools --upgrade
-
If synapse fails with ``missing "sodium.h"`` crypto errors, you may need
to manually upgrade PyNaCL, as synapse uses NaCl (http://nacl.cr.yp.to/) for
encryption and digital signatures.
@@ -225,13 +218,15 @@ directory of your choice::
$ cd synapse
The homeserver has a number of external dependencies, that are easiest
-to install by making setup.py do so, in --user mode::
+to install using pip and a virtualenv::
- $ python setup.py develop --user
+ $ virtualenv env
+ $ source env/bin/activate
+ $ python synapse/dependencies | xargs -i pip install
+ $ pip install setuptools_trial mock
-This will run a process of downloading and installing into your
-user's .local/lib directory all of the required dependencies that are
-missing.
+This will run a process of downloading and installing all the needed
+dependencies into a virtual env.
Once this is done, you may wish to run the homeserver's unit tests, to
check that everything is installed as it should be::
@@ -252,7 +247,7 @@ IMPORTANT: Before upgrading an existing homeserver to a new version, please
refer to UPGRADE.rst for any additional instructions.
Otherwise, simply re-install the new codebase over the current one - e.g.
-by ``pip install --user --process-dependency-links
+by ``pip install --process-dependency-links
https://github.com/matrix-org/synapse/tarball/master``
if using pip, or by ``git pull`` if running off a git working copy.
@@ -279,9 +274,9 @@ For the first form, simply pass the required hostname (of the machine) as the
$ python -m synapse.app.homeserver \
--server-name machine.my.domain.name \
- --config-path homeserver.config \
+ --config-path homeserver.yaml \
--generate-config
- $ python -m synapse.app.homeserver --config-path homeserver.config
+ $ python -m synapse.app.homeserver --config-path homeserver.yaml
Alternatively, you can run ``synctl start`` to guide you through the process.
@@ -301,9 +296,9 @@ SRV record, as that is the name other machines will expect it to have::
$ python -m synapse.app.homeserver \
--server-name YOURDOMAIN \
--bind-port 8448 \
- --config-path homeserver.config \
+ --config-path homeserver.yaml \
--generate-config
- $ python -m synapse.app.homeserver --config-path homeserver.config
+ $ python -m synapse.app.homeserver --config-path homeserver.yaml
You may additionally want to pass one or more "-v" options, in order to
|
