mirror of
https://git.anonymousland.org/anonymousland/synapse-product.git
synced 2024-10-01 08:25:44 -04:00
Rearrange the README
Move some bits of the README around. No words were changed in the making of this commit.
This commit is contained in:
parent
971edd04af
commit
cc03f4c58b
168
README.rst
168
README.rst
@ -26,6 +26,7 @@ bridge at 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
|
||||||
is sufficiently stable to be run as an internet-facing service for real usage!
|
is sufficiently stable to be run as an internet-facing service for real usage!
|
||||||
|
|
||||||
|
|
||||||
About Matrix
|
About Matrix
|
||||||
============
|
============
|
||||||
|
|
||||||
@ -87,6 +88,7 @@ Thanks for using Matrix!
|
|||||||
|
|
||||||
[1] End-to-end encryption is currently in development - see https://matrix.org/git/olm
|
[1] End-to-end encryption is currently in development - see https://matrix.org/git/olm
|
||||||
|
|
||||||
|
|
||||||
Synapse Installation
|
Synapse Installation
|
||||||
====================
|
====================
|
||||||
|
|
||||||
@ -195,6 +197,7 @@ 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.
|
||||||
|
|
||||||
|
|
||||||
Running Synapse
|
Running Synapse
|
||||||
===============
|
===============
|
||||||
|
|
||||||
@ -205,6 +208,42 @@ run (e.g. ``~/.synapse``), and::
|
|||||||
source ./bin/activate
|
source ./bin/activate
|
||||||
synctl start
|
synctl start
|
||||||
|
|
||||||
|
|
||||||
|
Running The Demo Web Client
|
||||||
|
===========================
|
||||||
|
|
||||||
|
The homeserver runs a web client by default at https://localhost:8448/.
|
||||||
|
|
||||||
|
If this is the first time you have used the client from that browser (it uses
|
||||||
|
HTML5 local storage to remember its config), you will need to log in to your
|
||||||
|
account. If you don't yet have an account, because you've just started the
|
||||||
|
homeserver for the first time, then you'll need to register one.
|
||||||
|
|
||||||
|
Registering A New Account
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
Your new user name will be formed partly from the hostname your server is
|
||||||
|
running as, and partly from a localpart you specify when you create the
|
||||||
|
account. Your name will take the form of::
|
||||||
|
|
||||||
|
@localpart:my.domain.here
|
||||||
|
(pronounced "at localpart on my dot domain dot here")
|
||||||
|
|
||||||
|
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
|
||||||
|
required due to lack of SRV records (e.g. @matthew:localhost:8448 on an
|
||||||
|
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
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
Just enter the ``@localpart:my.domain.here`` Matrix user ID and password into
|
||||||
|
the form and click the Login button.
|
||||||
|
|
||||||
|
|
||||||
Security Note
|
Security Note
|
||||||
=============
|
=============
|
||||||
|
|
||||||
@ -220,24 +259,6 @@ server on the same domain.
|
|||||||
See https://github.com/vector-im/vector-web/issues/1977 and
|
See https://github.com/vector-im/vector-web/issues/1977 and
|
||||||
https://developer.github.com/changes/2014-04-25-user-content-security for more details.
|
https://developer.github.com/changes/2014-04-25-user-content-security for more details.
|
||||||
|
|
||||||
Using PostgreSQL
|
|
||||||
================
|
|
||||||
|
|
||||||
As of Synapse 0.9, `PostgreSQL <http://www.postgresql.org>`_ is supported as an
|
|
||||||
alternative to the `SQLite <http://sqlite.org/>`_ database that Synapse has
|
|
||||||
traditionally used for convenience and simplicity.
|
|
||||||
|
|
||||||
The advantages of Postgres include:
|
|
||||||
|
|
||||||
* significant performance improvements due to the superior threading and
|
|
||||||
caching model, smarter query optimiser
|
|
||||||
* 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.
|
|
||||||
|
|
||||||
For information on how to install and use PostgreSQL, please see
|
|
||||||
`docs/postgres.rst <docs/postgres.rst>`_.
|
|
||||||
|
|
||||||
Platform Specific Instructions
|
Platform Specific Instructions
|
||||||
==============================
|
==============================
|
||||||
@ -340,6 +361,7 @@ 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``
|
||||||
|
|
||||||
|
|
||||||
Troubleshooting
|
Troubleshooting
|
||||||
===============
|
===============
|
||||||
|
|
||||||
@ -413,37 +435,6 @@ 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.
|
||||||
|
|
||||||
Synapse Development
|
|
||||||
===================
|
|
||||||
|
|
||||||
To check out a synapse for development, clone the git repo into a working
|
|
||||||
directory of your choice::
|
|
||||||
|
|
||||||
git clone https://github.com/matrix-org/synapse.git
|
|
||||||
cd synapse
|
|
||||||
|
|
||||||
Synapse has a number of external dependencies, that are easiest
|
|
||||||
to install using pip and a virtualenv::
|
|
||||||
|
|
||||||
virtualenv env
|
|
||||||
source env/bin/activate
|
|
||||||
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
|
|
||||||
dependencies into a virtual env.
|
|
||||||
|
|
||||||
Once this is done, you may wish to run Synapse's unit tests, to
|
|
||||||
check that everything is installed as it should be::
|
|
||||||
|
|
||||||
python setup.py test
|
|
||||||
|
|
||||||
This should end with a 'PASSED' result::
|
|
||||||
|
|
||||||
Ran 143 tests in 0.601s
|
|
||||||
|
|
||||||
PASSED (successes=143)
|
|
||||||
|
|
||||||
|
|
||||||
Upgrading an existing Synapse
|
Upgrading an existing Synapse
|
||||||
=============================
|
=============================
|
||||||
@ -454,6 +445,7 @@ versions of synapse.
|
|||||||
|
|
||||||
.. _UPGRADE.rst: UPGRADE.rst
|
.. _UPGRADE.rst: UPGRADE.rst
|
||||||
|
|
||||||
|
|
||||||
Setting up Federation
|
Setting up Federation
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
@ -521,41 +513,26 @@ http://localhost:8080. Simply run::
|
|||||||
|
|
||||||
This is mainly useful just for development purposes.
|
This is mainly useful just for development purposes.
|
||||||
|
|
||||||
Running The Demo Web Client
|
|
||||||
===========================
|
|
||||||
|
|
||||||
The homeserver runs a web client by default at https://localhost:8448/.
|
Using PostgreSQL
|
||||||
|
================
|
||||||
|
|
||||||
If this is the first time you have used the client from that browser (it uses
|
As of Synapse 0.9, `PostgreSQL <http://www.postgresql.org>`_ is supported as an
|
||||||
HTML5 local storage to remember its config), you will need to log in to your
|
alternative to the `SQLite <http://sqlite.org/>`_ database that Synapse has
|
||||||
account. If you don't yet have an account, because you've just started the
|
traditionally used for convenience and simplicity.
|
||||||
homeserver for the first time, then you'll need to register one.
|
|
||||||
|
|
||||||
|
The advantages of Postgres include:
|
||||||
|
|
||||||
Registering A New Account
|
* significant performance improvements due to the superior threading and
|
||||||
-------------------------
|
caching model, smarter query optimiser
|
||||||
|
* 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.
|
||||||
|
|
||||||
Your new user name will be formed partly from the hostname your server is
|
For information on how to install and use PostgreSQL, please see
|
||||||
running as, and partly from a localpart you specify when you create the
|
`docs/postgres.rst <docs/postgres.rst>`_.
|
||||||
account. Your name will take the form of::
|
|
||||||
|
|
||||||
@localpart:my.domain.here
|
|
||||||
(pronounced "at localpart on my dot domain dot here")
|
|
||||||
|
|
||||||
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
|
|
||||||
required due to lack of SRV records (e.g. @matthew:localhost:8448 on an
|
|
||||||
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
|
|
||||||
---------------------------------
|
|
||||||
|
|
||||||
Just enter the ``@localpart:my.domain.here`` Matrix user ID and password into
|
|
||||||
the form and click the Login button.
|
|
||||||
|
|
||||||
Identity Servers
|
Identity Servers
|
||||||
================
|
================
|
||||||
@ -614,6 +591,7 @@ Then update the `users` table in the database:
|
|||||||
UPDATE users SET password_hash='$2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
|
UPDATE users SET password_hash='$2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
|
||||||
WHERE name='@test:test.com';
|
WHERE name='@test:test.com';
|
||||||
|
|
||||||
|
|
||||||
Where's the spec?!
|
Where's the spec?!
|
||||||
==================
|
==================
|
||||||
|
|
||||||
@ -621,6 +599,38 @@ The source of the matrix spec lives at https://github.com/matrix-org/matrix-doc.
|
|||||||
A recent HTML snapshot of this lives at http://matrix.org/docs/spec
|
A recent HTML snapshot of this lives at http://matrix.org/docs/spec
|
||||||
|
|
||||||
|
|
||||||
|
Synapse Development
|
||||||
|
===================
|
||||||
|
|
||||||
|
To check out a synapse for development, clone the git repo into a working
|
||||||
|
directory of your choice::
|
||||||
|
|
||||||
|
git clone https://github.com/matrix-org/synapse.git
|
||||||
|
cd synapse
|
||||||
|
|
||||||
|
Synapse has a number of external dependencies, that are easiest
|
||||||
|
to install using pip and a virtualenv::
|
||||||
|
|
||||||
|
virtualenv env
|
||||||
|
source env/bin/activate
|
||||||
|
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
|
||||||
|
dependencies into a virtual env.
|
||||||
|
|
||||||
|
Once this is done, you may wish to run Synapse's unit tests, to
|
||||||
|
check that everything is installed as it should be::
|
||||||
|
|
||||||
|
python setup.py test
|
||||||
|
|
||||||
|
This should end with a 'PASSED' result::
|
||||||
|
|
||||||
|
Ran 143 tests in 0.601s
|
||||||
|
|
||||||
|
PASSED (successes=143)
|
||||||
|
|
||||||
|
|
||||||
Building Internal API Documentation
|
Building Internal API Documentation
|
||||||
===================================
|
===================================
|
||||||
|
|
||||||
@ -635,7 +645,6 @@ Building internal API documentation::
|
|||||||
python setup.py build_sphinx
|
python setup.py build_sphinx
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Help!! Synapse eats all my RAM!
|
Help!! Synapse eats all my RAM!
|
||||||
===============================
|
===============================
|
||||||
|
|
||||||
@ -650,4 +659,3 @@ matrix.org on. The default setting is currently 0.1, which is probably
|
|||||||
around a ~700MB footprint. You can dial it down further to 0.02 if
|
around a ~700MB footprint. You can dial it down further to 0.02 if
|
||||||
desired, which targets roughly ~512MB. Conversely you can dial it up if
|
desired, which targets roughly ~512MB. Conversely you can dial it up if
|
||||||
you need performance for lots of users and have a box with a lot of RAM.
|
you need performance for lots of users and have a box with a lot of RAM.
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user