From e709d61964834244c9dae673d4e6fefa6075cc5e Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Fri, 30 Jan 2015 16:56:53 +0000 Subject: Update documentation to recommend virtual env --- README.rst | 45 +++++++++++++++------------------------------ 1 file changed, 15 insertions(+), 30 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 768da3df64..ddc5d4f78c 100644 --- a/README.rst +++ b/README.rst @@ -95,7 +95,7 @@ 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:: @@ -103,19 +103,12 @@ Installing prerequisites on Mac OS X:: To install the synapse homeserver run:: - $ pip install --user --process-dependency-links https://github.com/matrix-org/synapse/tarball/master + $ virutalenv ~/.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. - -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:: - - $ # on Linux: - $ export PYTHONPATH=$HOME/.local/lib/python2.7/site-packages:$PYTHONPATH - - $ # on OSX: - $ export PYTHONPATH=$HOME/Library/Python/2.7/lib/python/site-packages:$PYTHONPATH +This installs synapse, along with the libraries it uses, into a virtual +environment under ``synapse``. For reliable VoIP calls to be routed via this homeserver, you MUST configure a TURN server. See docs/turn-howto.rst for details. @@ -182,23 +175,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 + $ ./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 +208,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 + $ 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:: -- cgit 1.4.1 From 33cf48118f3a4fcbd0ad31e52c2ad5b09abb2c60 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Fri, 30 Jan 2015 17:00:32 +0000 Subject: Tell people to "source" the activate script for virtualenv, Remove --user from pip install --- README.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index ddc5d4f78c..285865f5f0 100644 --- a/README.rst +++ b/README.rst @@ -121,19 +121,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. @@ -148,7 +148,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 @@ -176,7 +176,7 @@ To actually run your new homeserver, pick a working directory for Synapse to run (e.g. ``~/.synapse``), and:: $ cd ~/.synapse - $ ./bin/activate + $ source ./bin/activate $ synctl start Troubleshooting Running @@ -211,7 +211,7 @@ The homeserver has a number of external dependencies, that are easiest to install using pip and a virtualenv:: $ virtualenv env - $ env/bin/activate + $ source env/bin/activate $ python synapse/dependencies | xargs -i pip install $ pip install setuptools_trial mock @@ -237,7 +237,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. -- cgit 1.4.1 From 166c2cd4f3e3828668f73bb1f8248d850234fc5c Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 30 Jan 2015 17:11:29 +0000 Subject: add generate config instruction to the HS setup part --- README.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 285865f5f0..820b16d06c 100644 --- a/README.rst +++ b/README.rst @@ -110,6 +110,15 @@ To install the synapse homeserver run:: This installs synapse, along with the libraries it uses, into a virtual environment under ``synapse``. +To set up your homeserver, run (in your virtualenv, as before):: + + $ python -m synapse.app.homeserver \ + --server-name machine.my.domain.name \ + --config-path homeserver.config \ + --generate-config + +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. -- cgit 1.4.1 From 68bd7dfbb72ee37495bf180e277ace85aec6d34b Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 30 Jan 2015 17:37:37 +0000 Subject: s/homeserver.config/homeserver.yaml/ because that's what synctl looks for. --- README.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 820b16d06c..cac387292a 100644 --- a/README.rst +++ b/README.rst @@ -114,7 +114,7 @@ To set up your homeserver, run (in your virtualenv, as before):: $ python -m synapse.app.homeserver \ --server-name machine.my.domain.name \ - --config-path homeserver.config \ + --config-path homeserver.yaml \ --generate-config Substituting your host and domain name as appropriate. @@ -273,9 +273,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. @@ -295,9 +295,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 -- cgit 1.4.1 From e9dfc4cfae3a9abc85ae2882ebfbd0df689a9d2f Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 31 Jan 2015 06:09:59 +0100 Subject: fix OSX stuff and typos --- README.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index cac387292a..282a53873f 100644 --- a/README.rst +++ b/README.rst @@ -100,15 +100,16 @@ Installing prerequisites on Ubuntu or Debian:: Installing prerequisites on Mac OS X:: $ xcode-select --install + $ sudo pip install virtualenv To install the synapse homeserver run:: - $ virutalenv ~/.synapse + $ 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 a virtual -environment under ``synapse``. +environment under ``~/.synapse``. To set up your homeserver, run (in your virtualenv, as before):: -- cgit 1.4.1 From 8c52e6e8a1a9afd3e5d3164b7ac97c4986d6d353 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 2 Feb 2015 17:12:23 +0000 Subject: fix typo --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 282a53873f..01e0f36c84 100644 --- a/README.rst +++ b/README.rst @@ -222,7 +222,7 @@ to install using pip and a virtualenv:: $ virtualenv env $ source env/bin/activate - $ python synapse/dependencies | xargs -i pip install + $ python synapse/python_dependencies.py | xargs -i pip install $ pip install setuptools_trial mock This will run a process of downloading and installing all the needed -- cgit 1.4.1 From f3a4267757cbbfbfc996d2ececf34f98928fc90f Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 2 Feb 2015 17:31:58 +0000 Subject: less obscure xargs --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 01e0f36c84..e1fa4d75ff 100644 --- a/README.rst +++ b/README.rst @@ -222,7 +222,7 @@ to install using pip and a virtualenv:: $ virtualenv env $ source env/bin/activate - $ python synapse/python_dependencies.py | xargs -i pip install + $ python synapse/python_dependencies.py | xargs -n1 pip install $ pip install setuptools_trial mock This will run a process of downloading and installing all the needed -- cgit 1.4.1 From 03c25ebeaeceb737d35db480ac8d1e3ed5f81988 Mon Sep 17 00:00:00 2001 From: TurnedToDust Date: Fri, 6 Feb 2015 22:28:21 -0700 Subject: Update to README.rst Added Documentation regarding ArchLinux --- README.rst | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'README.rst') diff --git a/README.rst b/README.rst index e1fa4d75ff..dc1c14daa5 100644 --- a/README.rst +++ b/README.rst @@ -96,6 +96,11 @@ Installing prerequisites on Ubuntu or Debian:: $ sudo apt-get install build-essential python2.7-dev libffi-dev \ python-pip python-setuptools sqlite3 \ libssl-dev python-virtualenv libjpeg-dev + +Installing prerequisites on ArchLinux:: + + $ sudo pacman -S base-devel python2 python-pip \ + python-setuptools python-virtualenv sqlite3 Installing prerequisites on Mac OS X:: @@ -148,6 +153,31 @@ failing, e.g.:: On OSX, if you encounter clang: error: unknown argument: '-mno-fused-madd' you will need to export CFLAGS=-Qunused-arguments. +ArchLinux +-------------- +ArchLinux with the default installation of prerequisites, and your System itself. The installation may encounter a few Hiccups. + +python2.7 is Needed and I believe by default Arch uses Python3. + +pip is outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ): + - $ sudo pip2.7 install --upgrade pip + +You also may need to call 2.7 again during the install request: + - $ sudo pip2.7 install --process-dependency-links https://github.com/matrix-org/synapse/tarball/master + +If you encounter an error with lib bcrypt Causing an Wrong Elf Class: ELFCLASS32 (x64 Systems): +you need to remove py-bcrypt itself and then reinstall it to correctly compile under your architecture + - $ sudo pip2.7 uninstall py-bcrypt + - $ sudo pip2.7 install py-bcrypt + +During setup of homeserver you need to call (depending) python2.7 directly again: + - $ sudo python2.7 -m synapse.app.homeserver \ + --server-name machine.my.domain.name \ + --config-path homeserver.yaml \ + --generate-config + +Substituting your host and domain name as appropriate. + Windows Install --------------- Synapse can be installed on Cygwin. It requires the following Cygwin packages: @@ -207,6 +237,14 @@ fix try re-installing from PyPI or directly from $ # Install from github $ pip install --user https://github.com/pyca/pynacl/tarball/master +ArchLinux +--------- +If running $ synctl start , causes the following error + "subprocess.CalledProcessError: Command '['python', '-m', 'synapse.app.homeserver', '--daemonize', '-c', 'homeserver.yaml', '--pid-file', 'homeserver.pid']' returned non-zero exit status 1" + +You need to call 2.7 again by directly using + - $ python2.7 -m synapse.app.homeserver --daemonize -c homeserver.yaml --pid-file homeserver.pid + Homeserver Development ====================== -- cgit 1.4.1 From 0c0ae2e886821d323f0dbd6254c2b8ed7c61e8be Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 7 Feb 2015 20:24:46 +0000 Subject: clean up TurnedToDust's ArchLinux notes a bit --- README.rst | 44 ++++++++++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 18 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index dc1c14daa5..5eebe5b721 100644 --- a/README.rst +++ b/README.rst @@ -154,29 +154,37 @@ On OSX, if you encounter clang: error: unknown argument: '-mno-fused-madd' you will need to export CFLAGS=-Qunused-arguments. ArchLinux --------------- -ArchLinux with the default installation of prerequisites, and your System itself. The installation may encounter a few Hiccups. +--------- + +Installation on ArchLinux may encounter a few hiccups as Arch defaults to +python 3, but synapse currently assumes python 2.7 by default. -python2.7 is Needed and I believe by default Arch uses Python3. +pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):: -pip is outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ): - - $ sudo pip2.7 install --upgrade pip + $ sudo pip2.7 install --upgrade pip -You also may need to call 2.7 again during the install request: - - $ sudo pip2.7 install --process-dependency-links https://github.com/matrix-org/synapse/tarball/master +You also may need to explicitly specify python 2.7 again during the install +request:: + + $ pip2.7 install --process-dependency-links \ + https://github.com/matrix-org/synapse/tarball/master -If you encounter an error with lib bcrypt Causing an Wrong Elf Class: ELFCLASS32 (x64 Systems): -you need to remove py-bcrypt itself and then reinstall it to correctly compile under your architecture - - $ sudo pip2.7 uninstall py-bcrypt - - $ sudo pip2.7 install py-bcrypt +If you encounter an error with lib bcrypt causing an Wrong ELF Class: +ELFCLASS32 (x64 Systems), you may need to reinstall py-bcrypt to correctly +compile it under the right architecture. (This should not be needed if +installing under virtualenv):: + + $ sudo pip2.7 uninstall py-bcrypt + $ sudo pip2.7 install py-bcrypt -During setup of homeserver you need to call (depending) python2.7 directly again: - - $ sudo python2.7 -m synapse.app.homeserver \ +During setup of homeserver you need to call python2.7 directly again:: + + $ python2.7 -m synapse.app.homeserver \ --server-name machine.my.domain.name \ --config-path homeserver.yaml \ --generate-config -Substituting your host and domain name as appropriate. +...substituting your host and domain name as appropriate. Windows Install --------------- @@ -239,12 +247,12 @@ fix try re-installing from PyPI or directly from ArchLinux --------- -If running $ synctl start , causes the following error - "subprocess.CalledProcessError: Command '['python', '-m', 'synapse.app.homeserver', '--daemonize', '-c', 'homeserver.yaml', '--pid-file', 'homeserver.pid']' returned non-zero exit status 1" -You need to call 2.7 again by directly using - - $ python2.7 -m synapse.app.homeserver --daemonize -c homeserver.yaml --pid-file homeserver.pid +If running `$ synctl start` fails wit 'returned non-zero exit status 1', you will need to explicitly call Python2.7 - either running as:: + $ python2.7 -m synapse.app.homeserver --daemonize -c homeserver.yaml --pid-file homeserver.pid + +...or by editing synctl with the correct python executable. Homeserver Development ====================== -- cgit 1.4.1 From 2b8903ce2fe56a5cc72d48de9282ee4e176f4b83 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 14 Feb 2015 00:16:33 +0000 Subject: we federate on port 8448 nowadays... --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 5eebe5b721..d3778b9f2e 100644 --- a/README.rst +++ b/README.rst @@ -6,7 +6,7 @@ VoIP. The basics you need to know to get up and running are: - Everything in Matrix happens in a room. Rooms are distributed and do not exist on any single server. Rooms can be located using convenience aliases - like ``#matrix:matrix.org`` or ``#test:localhost:8008``. + like ``#matrix:matrix.org`` or ``#test:localhost:8448``. - Matrix user IDs look like ``@matthew:matrix.org`` (although in the future you will normally refer to yourself and others using a 3PID: email -- cgit 1.4.1 From 596daf6e68eefcce6f868157be6dfb22a51b82d6 Mon Sep 17 00:00:00 2001 From: brabo Date: Sun, 22 Feb 2015 18:52:59 +0100 Subject: added "cd ~/.synapse" before setup of the homeserver to generate our files in there instead of ~ --- README.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'README.rst') diff --git a/README.rst b/README.rst index d3778b9f2e..c2af7c9332 100644 --- a/README.rst +++ b/README.rst @@ -118,6 +118,7 @@ environment under ``~/.synapse``. To set up your homeserver, run (in your virtualenv, as before):: + $ cd ~/.synapse $ python -m synapse.app.homeserver \ --server-name machine.my.domain.name \ --config-path homeserver.yaml \ @@ -179,6 +180,7 @@ installing under virtualenv):: During setup of homeserver you need to call python2.7 directly again:: + $ cd ~/.synapse $ python2.7 -m synapse.app.homeserver \ --server-name machine.my.domain.name \ --config-path homeserver.yaml \ -- cgit 1.4.1