1
0

README.rst 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634
  1. .. contents::
  2. Introduction
  3. ============
  4. Matrix is an ambitious new ecosystem for open federated Instant Messaging and
  5. VoIP. The basics you need to know to get up and running are:
  6. - Everything in Matrix happens in a room. Rooms are distributed and do not
  7. exist on any single server. Rooms can be located using convenience aliases
  8. like ``#matrix:matrix.org`` or ``#test:localhost:8448``.
  9. - Matrix user IDs look like ``@matthew:matrix.org`` (although in the future
  10. you will normally refer to yourself and others using a 3PID: email
  11. address, phone number, etc rather than manipulating Matrix user IDs)
  12. The overall architecture is::
  13. client <----> homeserver <=====================> homeserver <----> client
  14. https://somewhere.org/_matrix https://elsewhere.net/_matrix
  15. ``#matrix:matrix.org`` is the official support room for Matrix, and can be
  16. accessed by any client from https://matrix.org/blog/try-matrix-now or via IRC
  17. bridge at irc://irc.freenode.net/matrix.
  18. Synapse is currently in rapid development, but as of version 0.5 we believe it
  19. is sufficiently stable to be run as an internet-facing service for real usage!
  20. About Matrix
  21. ============
  22. Matrix specifies a set of pragmatic RESTful HTTP JSON APIs as an open standard,
  23. which handle:
  24. - Creating and managing fully distributed chat rooms with no
  25. single points of control or failure
  26. - Eventually-consistent cryptographically secure synchronisation of room
  27. state across a global open network of federated servers and services
  28. - Sending and receiving extensible messages in a room with (optional)
  29. end-to-end encryption[1]
  30. - Inviting, joining, leaving, kicking, banning room members
  31. - Managing user accounts (registration, login, logout)
  32. - Using 3rd Party IDs (3PIDs) such as email addresses, phone numbers,
  33. Facebook accounts to authenticate, identify and discover users on Matrix.
  34. - Placing 1:1 VoIP and Video calls
  35. These APIs are intended to be implemented on a wide range of servers, services
  36. and clients, letting developers build messaging and VoIP functionality on top
  37. of the entirely open Matrix ecosystem rather than using closed or proprietary
  38. solutions. The hope is for Matrix to act as the building blocks for a new
  39. generation of fully open and interoperable messaging and VoIP apps for the
  40. internet.
  41. Synapse is a reference "homeserver" implementation of Matrix from the core
  42. development team at matrix.org, written in Python/Twisted for clarity and
  43. simplicity. It is intended to showcase the concept of Matrix and let folks see
  44. the spec in the context of a codebase and let you run your own homeserver and
  45. generally help bootstrap the ecosystem.
  46. In Matrix, every user runs one or more Matrix clients, which connect through to
  47. a Matrix homeserver which stores all their personal chat history and user
  48. account information - much as a mail client connects through to an IMAP/SMTP
  49. server. Just like email, you can either run your own Matrix homeserver and
  50. control and own your own communications and history or use one hosted by
  51. someone else (e.g. matrix.org) - there is no single point of control or
  52. mandatory service provider in Matrix, unlike WhatsApp, Facebook, Hangouts, etc.
  53. Synapse ships with two basic demo Matrix clients: webclient (a basic group chat
  54. web client demo implemented in AngularJS) and cmdclient (a basic Python
  55. command line utility which lets you easily see what the JSON APIs are up to).
  56. Meanwhile, iOS and Android SDKs and clients are available from:
  57. - https://github.com/matrix-org/matrix-ios-sdk
  58. - https://github.com/matrix-org/matrix-ios-kit
  59. - https://github.com/matrix-org/matrix-ios-console
  60. - https://github.com/matrix-org/matrix-android-sdk
  61. We'd like to invite you to join #matrix:matrix.org (via
  62. https://matrix.org/blog/try-matrix-now), run a homeserver, take a look at the
  63. Matrix spec at https://matrix.org/docs/spec and API docs at
  64. https://matrix.org/docs/api, experiment with the APIs and the demo clients, and
  65. report any bugs via https://matrix.org/jira.
  66. Thanks for using Matrix!
  67. [1] End-to-end encryption is currently in development - see https://matrix.org/git/olm
  68. Synapse Installation
  69. ====================
  70. Synapse is the reference python/twisted Matrix homeserver implementation.
  71. System requirements:
  72. - POSIX-compliant system (tested on Linux & OS X)
  73. - Python 2.7
  74. - At least 512 MB RAM.
  75. Synapse is written in python but some of the libraries is uses are written in
  76. C. So before we can install synapse itself we need a working C compiler and the
  77. header files for python C extensions.
  78. Installing prerequisites on Ubuntu or Debian::
  79. sudo apt-get install build-essential python2.7-dev libffi-dev \
  80. python-pip python-setuptools sqlite3 \
  81. libssl-dev python-virtualenv libjpeg-dev libxslt1-dev
  82. Installing prerequisites on ArchLinux::
  83. sudo pacman -S base-devel python2 python-pip \
  84. python-setuptools python-virtualenv sqlite3
  85. Installing prerequisites on CentOS 7::
  86. sudo yum install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
  87. lcms2-devel libwebp-devel tcl-devel tk-devel \
  88. python-virtualenv libffi-devel openssl-devel
  89. sudo yum groupinstall "Development Tools"
  90. Installing prerequisites on Mac OS X::
  91. xcode-select --install
  92. sudo easy_install pip
  93. sudo pip install virtualenv
  94. Installing prerequisites on Raspbian::
  95. sudo apt-get install build-essential python2.7-dev libffi-dev \
  96. python-pip python-setuptools sqlite3 \
  97. libssl-dev python-virtualenv libjpeg-dev
  98. sudo pip install --upgrade pip
  99. sudo pip install --upgrade ndg-httpsclient
  100. sudo pip install --upgrade virtualenv
  101. To install the synapse homeserver run::
  102. virtualenv -p python2.7 ~/.synapse
  103. source ~/.synapse/bin/activate
  104. pip install --upgrade setuptools
  105. pip install https://github.com/matrix-org/synapse/tarball/master
  106. This installs synapse, along with the libraries it uses, into a virtual
  107. environment under ``~/.synapse``. Feel free to pick a different directory
  108. if you prefer.
  109. In case of problems, please see the _Troubleshooting section below.
  110. Alternatively, Silvio Fricke has contributed a Dockerfile to automate the
  111. above in Docker at https://registry.hub.docker.com/u/silviof/docker-matrix/.
  112. Also, Martin Giess has created an auto-deployment process with vagrant/ansible,
  113. tested with VirtualBox/AWS/DigitalOcean - see https://github.com/EMnify/matrix-synapse-auto-deploy
  114. for details.
  115. To set up your homeserver, run (in your virtualenv, as before)::
  116. cd ~/.synapse
  117. python -m synapse.app.homeserver \
  118. --server-name machine.my.domain.name \
  119. --config-path homeserver.yaml \
  120. --generate-config \
  121. --report-stats=[yes|no]
  122. ...substituting your host and domain name as appropriate.
  123. This will generate you a config file that you can then customise, but it will
  124. also generate a set of keys for you. These keys will allow your Home Server to
  125. identify itself to other Home Servers, so don't lose or delete them. It would be
  126. wise to back them up somewhere safe. If, for whatever reason, you do need to
  127. change your Home Server's keys, you may find that other Home Servers have the
  128. old key cached. If you update the signing key, you should change the name of the
  129. key in the <server name>.signing.key file (the second word) to something different.
  130. By default, registration of new users is disabled. You can either enable
  131. registration in the config by specifying ``enable_registration: true``
  132. (it is then recommended to also set up CAPTCHA - see docs/CAPTCHA_SETUP), or
  133. you can use the command line to register new users::
  134. $ source ~/.synapse/bin/activate
  135. $ synctl start # if not already running
  136. $ register_new_matrix_user -c homeserver.yaml https://localhost:8448
  137. New user localpart: erikj
  138. Password:
  139. Confirm password:
  140. Success!
  141. For reliable VoIP calls to be routed via this homeserver, you MUST configure
  142. a TURN server. See docs/turn-howto.rst for details.
  143. Running Synapse
  144. ===============
  145. To actually run your new homeserver, pick a working directory for Synapse to
  146. run (e.g. ``~/.synapse``), and::
  147. cd ~/.synapse
  148. source ./bin/activate
  149. synctl start
  150. Using PostgreSQL
  151. ================
  152. As of Synapse 0.9, `PostgreSQL <http://www.postgresql.org>`_ is supported as an
  153. alternative to the `SQLite <http://sqlite.org/>`_ database that Synapse has
  154. traditionally used for convenience and simplicity.
  155. The advantages of Postgres include:
  156. * significant performance improvements due to the superior threading and
  157. caching model, smarter query optimiser
  158. * allowing the DB to be run on separate hardware
  159. * allowing basic active/backup high-availability with a "hot spare" synapse
  160. pointing at the same DB master, as well as enabling DB replication in
  161. synapse itself.
  162. The only disadvantage is that the code is relatively new as of April 2015 and
  163. may have a few regressions relative to SQLite.
  164. For information on how to install and use PostgreSQL, please see
  165. `docs/postgres.rst <docs/postgres.rst>`_.
  166. Platform Specific Instructions
  167. ==============================
  168. Debian
  169. ------
  170. Matrix provides official Debian packages via apt from http://matrix.org/packages/debian/.
  171. Note that these packages do not include a client - choose one from
  172. https://matrix.org/blog/try-matrix-now/ (or build your own with one of our SDKs :)
  173. Fedora
  174. ------
  175. Oleg Girko provides Fedora RPMs at
  176. https://obs.infoserver.lv/project/monitor/matrix-synapse
  177. ArchLinux
  178. ---------
  179. The quickest way to get up and running with ArchLinux is probably with Ivan
  180. Shapovalov's AUR package from
  181. https://aur.archlinux.org/packages/matrix-synapse/, which should pull in all
  182. the necessary dependencies.
  183. Alternatively, to install using pip a few changes may be needed as ArchLinux
  184. defaults to python 3, but synapse currently assumes python 2.7 by default:
  185. pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 )::
  186. sudo pip2.7 install --upgrade pip
  187. You also may need to explicitly specify python 2.7 again during the install
  188. request::
  189. pip2.7 install https://github.com/matrix-org/synapse/tarball/master
  190. If you encounter an error with lib bcrypt causing an Wrong ELF Class:
  191. ELFCLASS32 (x64 Systems), you may need to reinstall py-bcrypt to correctly
  192. compile it under the right architecture. (This should not be needed if
  193. installing under virtualenv)::
  194. sudo pip2.7 uninstall py-bcrypt
  195. sudo pip2.7 install py-bcrypt
  196. During setup of Synapse you need to call python2.7 directly again::
  197. cd ~/.synapse
  198. python2.7 -m synapse.app.homeserver \
  199. --server-name machine.my.domain.name \
  200. --config-path homeserver.yaml \
  201. --generate-config
  202. ...substituting your host and domain name as appropriate.
  203. FreeBSD
  204. -------
  205. Synapse can be installed via FreeBSD Ports or Packages contributed by Brendan Molloy from:
  206. - Ports: ``cd /usr/ports/net/py-matrix-synapse && make install clean``
  207. - Packages: ``pkg install py27-matrix-synapse``
  208. NixOS
  209. -----
  210. Robin Lambertz has packaged Synapse for NixOS at:
  211. https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix
  212. Windows Install
  213. ---------------
  214. Synapse can be installed on Cygwin. It requires the following Cygwin packages:
  215. - gcc
  216. - git
  217. - libffi-devel
  218. - openssl (and openssl-devel, python-openssl)
  219. - python
  220. - python-setuptools
  221. The content repository requires additional packages and will be unable to process
  222. uploads without them:
  223. - libjpeg8
  224. - libjpeg8-devel
  225. - zlib
  226. If you choose to install Synapse without these packages, you will need to reinstall
  227. ``pillow`` for changes to be applied, e.g. ``pip uninstall pillow`` ``pip install
  228. pillow --user``
  229. Troubleshooting:
  230. - You may need to upgrade ``setuptools`` to get this to work correctly:
  231. ``pip install setuptools --upgrade``.
  232. - You may encounter errors indicating that ``ffi.h`` is missing, even with
  233. ``libffi-devel`` installed. If you do, copy the ``.h`` files:
  234. ``cp /usr/lib/libffi-3.0.13/include/*.h /usr/include``
  235. - You may need to install libsodium from source in order to install PyNacl. If
  236. you do, you may need to create a symlink to ``libsodium.a`` so ``ld`` can find
  237. it: ``ln -s /usr/local/lib/libsodium.a /usr/lib/libsodium.a``
  238. Troubleshooting
  239. ===============
  240. Troubleshooting Installation
  241. ----------------------------
  242. Synapse requires pip 1.7 or later, so if your OS provides too old a version you
  243. may need to manually upgrade it::
  244. sudo pip install --upgrade pip
  245. Installing may fail with ``Could not find any downloads that satisfy the requirement pymacaroons-pynacl (from matrix-synapse==0.12.0)``.
  246. You can fix this by manually upgrading pip and virtualenv::
  247. sudo pip install --upgrade virtualenv
  248. You can next rerun ``virtualenv -p python2.7 synapse`` to update the virtual env.
  249. Installing may fail during installing virtualenv with ``InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning.``
  250. You can fix this by manually installing ndg-httpsclient::
  251. pip install --upgrade ndg-httpsclient
  252. Installing may fail with ``mock requires setuptools>=17.1. Aborting installation``.
  253. You can fix this by upgrading setuptools::
  254. pip install --upgrade setuptools
  255. If pip crashes mid-installation for reason (e.g. lost terminal), pip may
  256. refuse to run until you remove the temporary installation directory it
  257. created. To reset the installation::
  258. rm -rf /tmp/pip_install_matrix
  259. pip seems to leak *lots* of memory during installation. For instance, a Linux
  260. host with 512MB of RAM may run out of memory whilst installing Twisted. If this
  261. happens, you will have to individually install the dependencies which are
  262. failing, e.g.::
  263. pip install twisted
  264. On OS X, if you encounter clang: error: unknown argument: '-mno-fused-madd' you
  265. will need to export CFLAGS=-Qunused-arguments.
  266. Troubleshooting Running
  267. -----------------------
  268. If synapse fails with ``missing "sodium.h"`` crypto errors, you may need
  269. to manually upgrade PyNaCL, as synapse uses NaCl (http://nacl.cr.yp.to/) for
  270. encryption and digital signatures.
  271. Unfortunately PyNACL currently has a few issues
  272. (https://github.com/pyca/pynacl/issues/53) and
  273. (https://github.com/pyca/pynacl/issues/79) that mean it may not install
  274. correctly, causing all tests to fail with errors about missing "sodium.h". To
  275. fix try re-installing from PyPI or directly from
  276. (https://github.com/pyca/pynacl)::
  277. # Install from PyPI
  278. pip install --user --upgrade --force pynacl
  279. # Install from github
  280. pip install --user https://github.com/pyca/pynacl/tarball/master
  281. ArchLinux
  282. ~~~~~~~~~
  283. If running `$ synctl start` fails with 'returned non-zero exit status 1',
  284. you will need to explicitly call Python2.7 - either running as::
  285. python2.7 -m synapse.app.homeserver --daemonize -c homeserver.yaml
  286. ...or by editing synctl with the correct python executable.
  287. Synapse Development
  288. ===================
  289. To check out a synapse for development, clone the git repo into a working
  290. directory of your choice::
  291. git clone https://github.com/matrix-org/synapse.git
  292. cd synapse
  293. Synapse has a number of external dependencies, that are easiest
  294. to install using pip and a virtualenv::
  295. virtualenv env
  296. source env/bin/activate
  297. python synapse/python_dependencies.py | xargs -n1 pip install
  298. pip install setuptools_trial mock
  299. This will run a process of downloading and installing all the needed
  300. dependencies into a virtual env.
  301. Once this is done, you may wish to run Synapse's unit tests, to
  302. check that everything is installed as it should be::
  303. python setup.py test
  304. This should end with a 'PASSED' result::
  305. Ran 143 tests in 0.601s
  306. PASSED (successes=143)
  307. Upgrading an existing Synapse
  308. =============================
  309. The instructions for upgrading synapse are in `UPGRADE.rst`_.
  310. Please check these instructions as upgrading may require extra steps for some
  311. versions of synapse.
  312. .. _UPGRADE.rst: UPGRADE.rst
  313. Setting up Federation
  314. =====================
  315. In order for other homeservers to send messages to your server, it will need to
  316. be publicly visible on the internet, and they will need to know its host name.
  317. You have two choices here, which will influence the form of your Matrix user
  318. IDs:
  319. 1) Use the machine's own hostname as available on public DNS in the form of
  320. its A or AAAA records. This is easier to set up initially, perhaps for
  321. testing, but lacks the flexibility of SRV.
  322. 2) Set up a SRV record for your domain name. This requires you create a SRV
  323. record in DNS, but gives the flexibility to run the server on your own
  324. choice of TCP port, on a machine that might not be the same name as the
  325. domain name.
  326. For the first form, simply pass the required hostname (of the machine) as the
  327. --server-name parameter::
  328. python -m synapse.app.homeserver \
  329. --server-name machine.my.domain.name \
  330. --config-path homeserver.yaml \
  331. --generate-config
  332. python -m synapse.app.homeserver --config-path homeserver.yaml
  333. Alternatively, you can run ``synctl start`` to guide you through the process.
  334. For the second form, first create your SRV record and publish it in DNS. This
  335. needs to be named _matrix._tcp.YOURDOMAIN, and point at at least one hostname
  336. and port where the server is running. (At the current time synapse does not
  337. support clustering multiple servers into a single logical homeserver). The DNS
  338. record would then look something like::
  339. $ dig -t srv _matrix._tcp.machine.my.domain.name
  340. _matrix._tcp IN SRV 10 0 8448 machine.my.domain.name.
  341. At this point, you should then run the homeserver with the hostname of this
  342. SRV record, as that is the name other machines will expect it to have::
  343. python -m synapse.app.homeserver \
  344. --server-name YOURDOMAIN \
  345. --config-path homeserver.yaml \
  346. --generate-config
  347. python -m synapse.app.homeserver --config-path homeserver.yaml
  348. If you've already generated the config file, you need to edit the "server_name"
  349. in you ```homeserver.yaml``` file. If you've already started Synapse and a
  350. database has been created, you will have to recreate the database.
  351. You may additionally want to pass one or more "-v" options, in order to
  352. increase the verbosity of logging output; at least for initial testing.
  353. Running a Demo Federation of Synapses
  354. -------------------------------------
  355. If you want to get up and running quickly with a trio of homeservers in a
  356. private federation (``localhost:8080``, ``localhost:8081`` and
  357. ``localhost:8082``) which you can then access through the webclient running at
  358. http://localhost:8080. Simply run::
  359. demo/start.sh
  360. This is mainly useful just for development purposes.
  361. Running The Demo Web Client
  362. ===========================
  363. The homeserver runs a web client by default at https://localhost:8448/.
  364. If this is the first time you have used the client from that browser (it uses
  365. HTML5 local storage to remember its config), you will need to log in to your
  366. account. If you don't yet have an account, because you've just started the
  367. homeserver for the first time, then you'll need to register one.
  368. Registering A New Account
  369. -------------------------
  370. Your new user name will be formed partly from the hostname your server is
  371. running as, and partly from a localpart you specify when you create the
  372. account. Your name will take the form of::
  373. @localpart:my.domain.here
  374. (pronounced "at localpart on my dot domain dot here")
  375. Specify your desired localpart in the topmost box of the "Register for an
  376. account" form, and click the "Register" button. Hostnames can contain ports if
  377. required due to lack of SRV records (e.g. @matthew:localhost:8448 on an
  378. internal synapse sandbox running on localhost).
  379. If registration fails, you may need to enable it in the homeserver (see
  380. `Synapse Installation`_ above)
  381. Logging In To An Existing Account
  382. ---------------------------------
  383. Just enter the ``@localpart:my.domain.here`` Matrix user ID and password into
  384. the form and click the Login button.
  385. Identity Servers
  386. ================
  387. The job of authenticating 3PIDs and tracking which 3PIDs are associated with a
  388. given Matrix user is very security-sensitive, as there is obvious risk of spam
  389. if it is too easy to sign up for Matrix accounts or harvest 3PID data.
  390. Meanwhile the job of publishing the end-to-end encryption public keys for
  391. Matrix users is also very security-sensitive for similar reasons.
  392. Therefore the role of managing trusted identity in the Matrix ecosystem is
  393. farmed out to a cluster of known trusted ecosystem partners, who run 'Matrix
  394. Identity Servers' such as ``sydent``, whose role is purely to authenticate and
  395. track 3PID logins and publish end-user public keys.
  396. It's currently early days for identity servers as Matrix is not yet using 3PIDs
  397. as the primary means of identity and E2E encryption is not complete. As such,
  398. we are running a single identity server (https://matrix.org) at the current
  399. time.
  400. URL Previews
  401. ============
  402. Synapse 0.15.0 introduces an experimental new API for previewing URLs at
  403. /_matrix/media/r0/preview_url. This is disabled by default. To turn it on
  404. you must enable the `url_preview_enabled: True` config parameter and explicitly
  405. specify the IP ranges that Synapse is not allowed to spider for previewing in
  406. the `url_preview_ip_range_blacklist` configuration parameter. This is critical
  407. from a security perspective to stop arbitrary Matrix users spidering 'internal'
  408. URLs on your network. At the very least we recommend that your loopback and
  409. RFC1918 IP addresses are blacklisted.
  410. This also requires the optional lxml and netaddr python dependencies to be
  411. installed.
  412. Password reset
  413. ==============
  414. If a user has registered an email address to their account using an identity
  415. server, they can request a password-reset token via clients such as Vector.
  416. A manual password reset can be done via direct database access as follows.
  417. First calculate the hash of the new password:
  418. $ source ~/.synapse/bin/activate
  419. $ ./scripts/hash_password
  420. Password:
  421. Confirm password:
  422. $2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  423. Then update the `users` table in the database:
  424. UPDATE users SET password_hash='$2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  425. WHERE name='@test:test.com';
  426. Where's the spec?!
  427. ==================
  428. The source of the matrix spec lives at https://github.com/matrix-org/matrix-doc.
  429. A recent HTML snapshot of this lives at http://matrix.org/docs/spec
  430. Building Internal API Documentation
  431. ===================================
  432. Before building internal API documentation install sphinx and
  433. sphinxcontrib-napoleon::
  434. pip install sphinx
  435. pip install sphinxcontrib-napoleon
  436. Building internal API documentation::
  437. python setup.py build_sphinx
  438. Halp!! Synapse eats all my RAM!
  439. ===============================
  440. Synapse's architecture is quite RAM hungry currently - we deliberately
  441. cache a lot of recent room data and metadata in RAM in order to speed up
  442. common requests. We'll improve this in future, but for now the easiest
  443. way to either reduce the RAM usage (at the risk of slowing things down)
  444. is to set the almost-undocumented ``SYNAPSE_CACHE_FACTOR`` environment
  445. variable. Roughly speaking, a SYNAPSE_CACHE_FACTOR of 1.0 will max out
  446. at around 3-4GB of resident memory - this is what we currently run the
  447. matrix.org on. The default setting is currently 0.1, which is probably
  448. around a ~700MB footprint. You can dial it down further to 0.02 if
  449. desired, which targets roughly ~512MB. Conversely you can dial it up if
  450. you need performance for lots of users and have a box with a lot of RAM.